### GET /api/config

Source: https://context7.com/dullage/flatnotes/llms.txt

Retrieves server-side configuration settings.

```APIDOC
## GET /api/config

### Description
Returns server-side configuration settings required by the UI, including authentication type and quick access settings.

### Method
GET

### Endpoint
/api/config

### Response
#### Success Response (200)
- **authType** (string) - Authentication method
- **quickAccessHide** (boolean) - Whether to hide quick access
- **quickAccessTitle** (string) - Title for quick access section
- **quickAccessTerm** (string) - Search term for quick access
- **quickAccessSort** (string) - Sort field for quick access
- **quickAccessLimit** (integer) - Limit for quick access results

#### Response Example
{
  "authType": "password",
  "quickAccessHide": false,
  "quickAccessTitle": "RECENTLY MODIFIED",
  "quickAccessTerm": "*",
  "quickAccessSort": "lastModified",
  "quickAccessLimit": 4
}
```

--------------------------------

### Tagging Notes Syntax

Source: https://context7.com/dullage/flatnotes/llms.txt

Example of how to add hashtags to note content for indexing.

```markdown
# Holiday Ideas

- Amsterdam
- Geneva
- Zurich
- Rome

#personal #holiday
```

--------------------------------

### JavaScript: Full Usage Example

Source: https://context7.com/dullage/flatnotes/llms.txt

Demonstrates a complete workflow: logging in, creating a note, searching for it, and retrieving all tags.

```javascript
async function main() {
  await login("user", "changeMe!");

  // Create a note
  const note = await createNote("My Note", "# Hello World\n\n#greeting");
  console.log("Created:", note.title);

  // Search for notes
  const results = await searchNotes("#greeting");
  console.log("Found:", results.length, "notes");

  // Get all tags
  const tags = await getTags();
  console.log("Tags:", tags);
}
```

--------------------------------

### Markdown Wikilink Example

Source: https://context7.com/dullage/flatnotes/llms.txt

Demonstrates how to link to other notes using wikilink syntax within markdown content.

```markdown
# Project Overview

This project is related to the [[Meeting Notes]] from last week.

See also:
- [[Technical Specifications]]
- [[Team Members]]
```

--------------------------------

### JavaScript API Client Setup

Source: https://context7.com/dullage/flatnotes/llms.txt

Initializes an Axios instance for interacting with the Flatnotes API, including request interceptors for authentication.

```javascript
import axios from "axios";

const api = axios.create({
  baseURL: "http://localhost:8080",
});

// Store and use authentication token
let authToken = null;

api.interceptors.request.use((config) => {
  if (authToken && config.url !== "api/token") {
    config.headers.Authorization = `Bearer ${authToken}`;
  }
  return config;
});
```

--------------------------------

### Get Server Configuration

Source: https://context7.com/dullage/flatnotes/llms.txt

Retrieve server-side configuration settings including authentication type and quick access settings.

```bash
curl -X GET "http://localhost:8080/api/config"
```

--------------------------------

### JavaScript: Get All Tags

Source: https://context7.com/dullage/flatnotes/llms.txt

Fetches a list of all available tags used in the notes.

```javascript
async function getTags() {
  const response = await api.get("api/tags");
  return response.data;
}
```

--------------------------------

### GET /health

Source: https://context7.com/dullage/flatnotes/llms.txt

Checks the health status of the server.

```APIDOC
## GET /health

### Description
A lightweight endpoint for monitoring that returns "OK" when the server is running.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - "OK"
```

--------------------------------

### GET /api/auth-check

Source: https://context7.com/dullage/flatnotes/llms.txt

Verifies the validity of the provided authentication token.

```APIDOC
## GET /api/auth-check

### Description
A lightweight endpoint that returns "OK" if the user is authenticated, useful for checking token validity.

### Method
GET

### Endpoint
/api/auth-check

### Response
#### Success Response (200)
- **body** (string) - "OK"
```

--------------------------------

### Docker Compose for Flatnotes

Source: https://github.com/dullage/flatnotes/blob/develop/README.md

This Docker Compose configuration simplifies the deployment of Flatnotes. It defines the service, image, environment variables, volumes, and port mappings for a robust setup.

```yaml
version: "3" 

services:
  flatnotes:
    container_name: flatnotes
    image: dullage/flatnotes:latest
    environment:
      PUID: 1000
      PGID: 1000
      FLATNOTES_AUTH_TYPE: "password"
      FLATNOTES_USERNAME: "user"
      FLATNOTES_PASSWORD: "changeMe!"
      FLATNOTES_SECRET_KEY: "aLongRandomSeriesOfCharacters"
    volumes:
      - "./data:/data"
      # Optional. Allows you to save the search index in a different location: 
      # - "./index:/data/.flatnotes"
    ports:
      - "8080:8080"
    restart: unless-stopped
```

--------------------------------

### JavaScript: Login and Get Token

Source: https://context7.com/dullage/flatnotes/llms.txt

Authenticates a user with the API and retrieves an access token. Supports optional TOTP for enhanced security.

```javascript
async function login(username, password, totp = null) {
  const response = await api.post("api/token", {
    username,
    password: totp ? password + totp : password,
  });
  authToken = response.data.access_token;
  return authToken;
}
```

--------------------------------

### GET /api/search

Source: https://context7.com/dullage/flatnotes/llms.txt

Performs a full-text search across all notes.

```APIDOC
## GET /api/search

### Description
Performs a powerful full-text search across all notes with support for AND/OR operators, phrase matching, wildcards, field-specific searches, and date ranges.

### Method
GET

### Endpoint
/api/search

### Parameters
#### Query Parameters
- **term** (string) - Required - The search query term
```

--------------------------------

### GET /api/notes/{title}

Source: https://context7.com/dullage/flatnotes/llms.txt

Retrieves the content and metadata of a specific note by its title.

```APIDOC
## GET /api/notes/{title}

### Description
Retrieves a specific note by its title. The title should be URL-encoded if it contains special characters.

### Method
GET

### Endpoint
/api/notes/{title}

### Parameters
#### Path Parameters
- **title** (string) - Required - The title of the note to retrieve

### Response
#### Success Response (200)
- **title** (string) - The note title
- **content** (string) - The note content
- **lastModified** (number) - Timestamp of last modification
```

--------------------------------

### Authenticate User and Get Access Token

Source: https://context7.com/dullage/flatnotes/llms.txt

Use this endpoint to authenticate with the Flatnotes API. Supports basic password authentication and TOTP two-factor authentication by appending the code to the password.

```bash
curl -X POST "http://localhost:8080/api/token" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "user",
    "password": "changeMe!"
  }'
```

```bash
curl -X POST "http://localhost:8080/api/token" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "user",
    "password": "changeMe!123456"
  }'
```

--------------------------------

### GET /api/attachments/{filename}

Source: https://context7.com/dullage/flatnotes/llms.txt

Retrieves an uploaded attachment by its filename.

```APIDOC
## GET /api/attachments/{filename}

### Description
Retrieves an uploaded attachment by filename.

### Method
GET

### Endpoint
/api/attachments/{filename}

### Parameters
#### Path Parameters
- **filename** (string) - Required - The name of the file to retrieve.
```

--------------------------------

### GET /api/tags

Source: https://context7.com/dullage/flatnotes/llms.txt

Retrieves a list of all unique tags indexed across all notes.

```APIDOC
## GET /api/tags

### Description
Returns a list of all unique tags currently indexed across all notes.

### Method
GET

### Endpoint
/api/tags

### Response
#### Success Response (200)
- **tags** (array) - List of unique tag strings

#### Response Example
["holiday", "meeting", "personal", "work"]
```

--------------------------------

### JavaScript: Get a Note by Title

Source: https://context7.com/dullage/flatnotes/llms.txt

Retrieves a specific note using its title. The title is URL-encoded to ensure correct API request.

```javascript
async function getNote(title) {
  const response = await api.get(`api/notes/${encodeURIComponent(title)}`);
  return response.data;
}
```

--------------------------------

### GET /api/search

Source: https://context7.com/dullage/flatnotes/llms.txt

Performs a search across notes based on provided terms, filters, and sorting parameters.

```APIDOC
## GET /api/search

### Description
Searches for notes using various criteria such as tags, field-specific queries, date ranges, or wildcards.

### Method
GET

### Endpoint
/api/search

### Parameters
#### Query Parameters
- **term** (string) - Required - The search query string (e.g., #tag, title:value, wildcard).
- **sort** (string) - Optional - Field to sort results by (e.g., title, lastModified).
- **order** (string) - Optional - Sort order (asc or desc).
- **limit** (integer) - Optional - Maximum number of results to return.

### Response
#### Success Response (200)
- **title** (string) - Note title
- **lastModified** (float) - Timestamp of last modification
- **score** (float) - Search relevance score
- **titleHighlights** (string) - HTML highlighted title
- **contentHighlights** (string) - HTML highlighted content snippet
- **tagMatches** (array) - List of matching tags

#### Response Example
[
  {
    "title": "Project Meeting Notes",
    "lastModified": 1699876600.456,
    "score": 2.5,
    "titleHighlights": "<b class=\"match term0\">Project</b> Meeting Notes",
    "contentHighlights": "Discussed <b class=\"match term0\">project</b> <b class=\"match term1\">timeline</b>",
    "tagMatches": ["work"]
  }
]
```

--------------------------------

### Deploy with Docker Compose

Source: https://context7.com/dullage/flatnotes/llms.txt

Configuration for deploying Flatnotes using docker-compose.yml.

```yaml
version: "3"

services:
  flatnotes:
    container_name: flatnotes
    image: dullage/flatnotes:latest
    environment:
      PUID: 1000
      PGID: 1000
      FLATNOTES_AUTH_TYPE: "password"  # none, read_only, password, or totp
      FLATNOTES_USERNAME: "user"
      FLATNOTES_PASSWORD: "changeMe!"
      FLATNOTES_SECRET_KEY: "aLongRandomSeriesOfCharacters"
      # Optional: TOTP for 2FA
      # FLATNOTES_TOTP_KEY: "anotherLongRandomString"
      # Optional: Custom quick access section
      FLATNOTES_QUICK_ACCESS_TITLE: "PINNED NOTES"
      FLATNOTES_QUICK_ACCESS_TERM: "#pinned"
      FLATNOTES_QUICK_ACCESS_SORT: "title"
      FLATNOTES_QUICK_ACCESS_LIMIT: 8
      # Optional: Path prefix for reverse proxy
      # FLATNOTES_PATH_PREFIX: "/notes"
    volumes:
      - "./data:/data"
      # Optional: Separate index storage
      # - "./index:/data/.flatnotes"
    ports:
      - "8080:8080"
    restart: unless-stopped
```

--------------------------------

### Run Flatnotes with Docker

Source: https://github.com/dullage/flatnotes/blob/develop/README.md

Use this command to run Flatnotes as a Docker container. Ensure you set appropriate environment variables for authentication and map the data volume.

```shell
docker run -d \
  -e "PUID=1000" \
  -e "PGID=1000" \
  -e "FLATNOTES_AUTH_TYPE=password" \
  -e "FLATNOTES_USERNAME=user" \
  -e 'FLATNOTES_PASSWORD=changeMe!' \
  -e "FLATNOTES_SECRET_KEY=aLongRandomSeriesOfCharacters" \
  -v "$(pwd)/data:/data" \
  -p "8080:8080" \
  dullage/flatnotes:latest
```

--------------------------------

### Run Docker Container

Source: https://context7.com/dullage/flatnotes/llms.txt

Command to run the Flatnotes container directly.

```bash
docker run -d \
  -e "PUID=1000" \
  -e "PGID=1000" \
  -e "FLATNOTES_AUTH_TYPE=password" \
  -e "FLATNOTES_USERNAME=user" \
  -e "FLATNOTES_PASSWORD=changeMe!" \
  -e "FLATNOTES_SECRET_KEY=aLongRandomSeriesOfCharacters" \
  -v "$(pwd)/data:/data" \
  -p "8080:8080" \
  dullage/flatnotes:latest
```

--------------------------------

### Create a New Note

Source: https://context7.com/dullage/flatnotes/llms.txt

Use this endpoint to create a new markdown note. The title will be used as the filename. Ensure the title is a valid filename.

```bash
curl -X POST "http://localhost:8080/api/notes" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Meeting Notes",
    "content": "# Meeting Notes\n\nDiscussed project timeline.\n\n#work #meeting"
  }'
```

--------------------------------

### Combine Tag and Content Search using curl

Source: https://context7.com/dullage/flatnotes/llms.txt

Use curl to search for notes tagged 'work' and containing the word 'project'. Replace '<token>' with your authentication token.

```bash
curl -X GET "http://localhost:8080/api/search?term=tags:work%20AND%20project" \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### JavaScript: Create a New Note

Source: https://context7.com/dullage/flatnotes/llms.txt

Sends a POST request to create a new note with a specified title and content.

```javascript
async function createNote(title, content) {
  const response = await api.post("api/notes", { title, content });
  return response.data;
}
```

--------------------------------

### Retrieve a Specific Note

Source: https://context7.com/dullage/flatnotes/llms.txt

Fetches a note by its title. If the title contains special characters, it must be URL-encoded.

```bash
curl -X GET "http://localhost:8080/api/notes/Meeting%20Notes" \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### List All Tags

Source: https://context7.com/dullage/flatnotes/llms.txt

Retrieve a list of all unique tags currently indexed across all notes.

```bash
curl -X GET "http://localhost:8080/api/tags" \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### Upload Attachment

Source: https://context7.com/dullage/flatnotes/llms.txt

Upload a file to the attachments folder using multipart/form-data.

```bash
curl -X POST "http://localhost:8080/api/attachments" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@/path/to/image.png"
```

--------------------------------

### Search Notes via API

Source: https://context7.com/dullage/flatnotes/llms.txt

Perform various search queries including tags, fields, date ranges, and wildcards. Requires an Authorization header with a Bearer token.

```bash
curl -X GET "http://localhost:8080/api/search?term=%23work" \
  -H "Authorization: Bearer <token>"
```

```bash
curl -X GET "http://localhost:8080/api/search?term=title:meeting%20AND%20tags:work" \
  -H "Authorization: Bearer <token>"
```

```bash
curl -X GET "http://localhost:8080/api/search?term=last_modified:[20230101%20to%2020231231]" \
  -H "Authorization: Bearer <token>"
```

```bash
curl -X GET "http://localhost:8080/api/search?term=proj*" \
  -H "Authorization: Bearer <token>"
```

```bash
curl -X GET "http://localhost:8080/api/search?term=*&sort=title&order=asc" \
  -H "Authorization: Bearer <token>"
```

```bash
curl -X GET "http://localhost:8080/api/search?term=*&sort=lastModified&order=desc&limit=10" \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### Server Health Check

Source: https://context7.com/dullage/flatnotes/llms.txt

Lightweight endpoint to verify if the server is running.

```bash
curl -X GET "http://localhost:8080/health"
```

--------------------------------

### Download Attachment

Source: https://context7.com/dullage/flatnotes/llms.txt

Retrieve an uploaded attachment by filename.

```bash
curl -X GET "http://localhost:8080/api/attachments/image.png" \
  -H "Authorization: Bearer <token>" \
  --output downloaded-image.png
```

--------------------------------

### POST /api/notes

Source: https://context7.com/dullage/flatnotes/llms.txt

Creates a new note with a specified title and content.

```APIDOC
## POST /api/notes

### Description
Creates a new note with the specified title and optional content. The title becomes the filename (with .md extension).

### Method
POST

### Endpoint
/api/notes

### Request Body
- **title** (string) - Required - The title of the note
- **content** (string) - Optional - The content of the note

### Request Example
{
  "title": "Meeting Notes",
  "content": "# Meeting Notes\n\nDiscussed project timeline."
}

### Response
#### Success Response (200)
- **title** (string) - The note title
- **content** (string) - The note content
- **lastModified** (number) - Timestamp of last modification
```

--------------------------------

### Verify Authentication Status

Source: https://context7.com/dullage/flatnotes/llms.txt

A simple endpoint to check if the provided authentication token is valid. Returns 'OK' if the user is authenticated.

```bash
curl -X GET "http://localhost:8080/api/auth-check" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

--------------------------------

### Perform Full-Text Search

Source: https://context7.com/dullage/flatnotes/llms.txt

Searches across all notes using various query options including AND/OR, phrase matching, wildcards, and date ranges. The search term must be URL-encoded.

```bash
# Basic search (AND by default)
curl -X GET "http://localhost:8080/api/search?term=project%20timeline" \
  -H "Authorization: Bearer <token>"
```

```bash
# OR search
curl -X GET "http://localhost:8080/api/search?term=project%20OR%20meeting" \
  -H "Authorization: Bearer <token>"
```

```bash
# Phrase search
curl -X GET "http://localhost:8080/api/search?term=%22project%20timeline%22" \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### Search Notes with Tags using curl

Source: https://context7.com/dullage/flatnotes/llms.txt

Use curl to search for notes tagged with '#personal'. Ensure you replace '<token>' with your actual authentication token.

```bash
curl -X GET "http://localhost:8080/api/search?term=%23personal" \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### POST /api/attachments

Source: https://context7.com/dullage/flatnotes/llms.txt

Uploads a file to the attachments folder.

```APIDOC
## POST /api/attachments

### Description
Uploads a file (typically an image) to the attachments folder.

### Method
POST

### Endpoint
/api/attachments

### Request Body
- **file** (binary) - Required - The file to upload.

### Response
#### Success Response (200)
- **filename** (string) - The name of the uploaded file
- **url** (string) - The URL path to access the file

#### Response Example
{
  "filename": "image.png",
  "url": "/attachments/image.png"
}
```

--------------------------------

### POST /api/token

Source: https://context7.com/dullage/flatnotes/llms.txt

Authenticates a user and returns a JWT access token. If TOTP is enabled, the 6-digit code must be appended to the password.

```APIDOC
## POST /api/token

### Description
Authenticates a user and returns a JWT access token for subsequent API requests. When TOTP is enabled, append the 6-digit code to the password.

### Method
POST

### Endpoint
/api/token

### Request Body
- **username** (string) - Required - The user's username
- **password** (string) - Required - The user's password (optionally appended with TOTP code)

### Request Example
{
  "username": "user",
  "password": "changeMe!"
}

### Response
#### Success Response (200)
- **access_token** (string) - The JWT access token
- **token_type** (string) - The type of token (bearer)

#### Response Example
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}
```

--------------------------------

### Find Notes Without Tags using curl

Source: https://context7.com/dullage/flatnotes/llms.txt

Use curl to find notes that do not have any tags assigned. Replace '<token>' with your authentication token.

```bash
curl -X GET "http://localhost:8080/api/search?term=NOT%20tags:*" \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### JavaScript: Upload Attachment

Source: https://context7.com/dullage/flatnotes/llms.txt

Uploads a file as an attachment to the notes. Requires the file object and sets the appropriate content type header.

```javascript
async function uploadAttachment(file) {
  const formData = new FormData();
  formData.append("file", file);
  const response = await api.post("api/attachments", formData, {
    headers: { "Content-Type": "multipart/form-data" },
  });
  return response.data;
}
```

--------------------------------

### JavaScript: Search Notes

Source: https://context7.com/dullage/flatnotes/llms.txt

Performs a search query against the notes. Allows specifying search term, sort order, and result limit.

```javascript
async function searchNotes(term, sort = "score", order = "desc", limit = null) {
  const response = await api.get("api/search", {
    params: { term, sort, order, limit },
  });
  return response.data;
}
```

--------------------------------

### JavaScript: Update a Note

Source: https://context7.com/dullage/flatnotes/llms.txt

Updates an existing note by its title, allowing modification of both title and content. Only provided fields are updated.

```javascript
async function updateNote(title, newTitle = null, newContent = null) {
  const response = await api.patch(`api/notes/${encodeURIComponent(title)}`, {
    newTitle,
    newContent,
  });
  return response.data;
}
```

--------------------------------

### Update an Existing Note

Source: https://context7.com/dullage/flatnotes/llms.txt

Partially updates a note's content or title. Only the fields provided in the request body will be modified.

```bash
# Update content only
curl -X PATCH "http://localhost:8080/api/notes/Meeting%20Notes" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "newContent": "# Meeting Notes\n\nDiscussed project timeline.\n\n## Action Items\n- Review proposal\n- Schedule follow-up\n\n#work #meeting"
  }'
```

```bash
# Rename note
curl -X PATCH "http://localhost:8080/api/notes/Meeting%20Notes" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "newTitle": "Project Meeting Notes"
  }'
```

--------------------------------

### Search Notes by Tag Field using curl

Source: https://context7.com/dullage/flatnotes/llms.txt

Use curl to search for notes where the 'holiday' tag is present in the tags field. Replace '<token>' with your authentication token.

```bash
curl -X GET "http://localhost:8080/api/search?term=tags:holiday" \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### PATCH /api/notes/{title}

Source: https://context7.com/dullage/flatnotes/llms.txt

Updates an existing note's title or content.

```APIDOC
## PATCH /api/notes/{title}

### Description
Updates an existing note's title and/or content. Both fields are optional.

### Method
PATCH

### Endpoint
/api/notes/{title}

### Parameters
#### Path Parameters
- **title** (string) - Required - The current title of the note

### Request Body
- **newContent** (string) - Optional - The updated content
- **newTitle** (string) - Optional - The new title for the note

### Response
#### Success Response (200)
- **title** (string) - The updated title
- **content** (string) - The updated content
- **lastModified** (number) - Timestamp of last modification
```

--------------------------------

### DELETE /api/notes/{title}

Source: https://context7.com/dullage/flatnotes/llms.txt

Permanently deletes a note.

```APIDOC
## DELETE /api/notes/{title}

### Description
Permanently deletes a note.

### Method
DELETE

### Endpoint
/api/notes/{title}

### Parameters
#### Path Parameters
- **title** (string) - Required - The title of the note to delete
```

--------------------------------

### Delete a Note

Source: https://context7.com/dullage/flatnotes/llms.txt

Permanently removes a note from the system. This operation is irreversible.

```bash
curl -X DELETE "http://localhost:8080/api/notes/Project%20Meeting%20Notes" \
  -H "Authorization: Bearer <token>"
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.