KosmoKrator

productivity

Readwise Lua API for KosmoKrator Agents

Agent-facing Lua documentation and function reference for the Readwise KosmoKrator integration.

Lua Namespace

Agents call this integration through app.integrations.readwise.*. Use lua_read_doc("integrations.readwise") inside KosmoKrator to discover the same reference at runtime.

Call Lua from the Headless CLI

Use kosmo integrations:lua when a shell script, CI job, cron job, or another coding CLI should run a deterministic Readwise workflow without starting an interactive agent session.

Inline Lua call 
kosmo integrations:lua --eval 'dump(app.integrations.readwise.check_auth({}))' --json
Read Lua docs headlessly 
kosmo integrations:lua --eval 'print(docs.read("readwise"))' --json
kosmo integrations:lua --eval 'print(docs.read("readwise.check_auth"))' --json

Workflow file

Put repeatable logic in a Lua file, then execute it with JSON output for the calling process.

workflow.lua 
local readwise = app.integrations.readwise
local result = readwise.check_auth({})

dump(result)
Run the workflow 
kosmo integrations:lua workflow.lua --json
kosmo integrations:lua workflow.lua --force --json
Namespace note. integrations:lua exposes app.integrations.readwise, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.readwise.default.* or app.integrations.readwise.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need Readwise, use the narrower mcp:lua command.

MCP Lua command 
# Use mcp:lua for MCP-only scripts; use integrations:lua for this integration namespace.
kosmo mcp:lua --eval 'dump(mcp.servers())' --json

Agent-Facing Lua Docs

This is the rendered version of the full Lua documentation exposed to agents when they inspect the integration namespace.

Readwise

Use the readwise namespace to work with both Readwise highlights/books and Reader documents.

Authentication uses a Readwise access token in the Authorization: Token ... header. Agents should not pass the token manually.

Readwise v2

  • readwise_list_books and readwise_get_book read source books/articles.
  • readwise_list_highlights, readwise_get_highlight, readwise_create_highlights, readwise_update_highlight, and readwise_delete_highlight manage highlights.
  • readwise_export_highlights is the preferred sync endpoint. Use updatedAfter and pageCursor for incremental exports.
  • readwise_get_review_queue retrieves review queue items.
  • Book and highlight tag tools use book_id, highlight_id, and tag_id path fields.

Reader v3

  • readwise_save_document saves a URL or HTML document to Reader.
  • readwise_list_documents accepts filters such as updatedAfter, location, category, tag, limit, and pageCursor.
  • readwise_update_document updates metadata, tags, notes, location, category, and seen state for one document.
  • readwise_bulk_update_documents accepts an updates array.
  • readwise_delete_document deletes a Reader document.
  • readwise_list_reader_tags lists Reader tags for filtering.

Examples

readwise_save_document({
  url = "https://example.test/article",
  payload = {
    tags = {"research", "later"},
    saved_using = "agent"
  }
})
readwise_list_documents({
  payload = {
    location = "archive",
    updatedAfter = "2026-05-01T00:00:00Z",
    limit = 100
  }
})
readwise_export_highlights({
  payload = {
    updatedAfter = "2026-05-01T00:00:00Z",
    pageCursor = "cursor-from-previous-response"
  }
})

The raw readwise_api_get, readwise_api_post, readwise_api_patch, and readwise_api_delete tools only accept relative paths such as /api/v3/list/; full URLs are rejected.

Raw agent markdown 
# Readwise

Use the `readwise` namespace to work with both Readwise highlights/books and Reader documents.

Authentication uses a Readwise access token in the `Authorization: Token ...` header. Agents should not pass the token manually.

## Readwise v2

- `readwise_list_books` and `readwise_get_book` read source books/articles.
- `readwise_list_highlights`, `readwise_get_highlight`, `readwise_create_highlights`, `readwise_update_highlight`, and `readwise_delete_highlight` manage highlights.
- `readwise_export_highlights` is the preferred sync endpoint. Use `updatedAfter` and `pageCursor` for incremental exports.
- `readwise_get_review_queue` retrieves review queue items.
- Book and highlight tag tools use `book_id`, `highlight_id`, and `tag_id` path fields.

## Reader v3

- `readwise_save_document` saves a URL or HTML document to Reader.
- `readwise_list_documents` accepts filters such as `updatedAfter`, `location`, `category`, `tag`, `limit`, and `pageCursor`.
- `readwise_update_document` updates metadata, tags, notes, location, category, and seen state for one document.
- `readwise_bulk_update_documents` accepts an `updates` array.
- `readwise_delete_document` deletes a Reader document.
- `readwise_list_reader_tags` lists Reader tags for filtering.

## Examples

```lua
readwise_save_document({
  url = "https://example.test/article",
  payload = {
    tags = {"research", "later"},
    saved_using = "agent"
  }
})
```

```lua
readwise_list_documents({
  payload = {
    location = "archive",
    updatedAfter = "2026-05-01T00:00:00Z",
    limit = 100
  }
})
```

```lua
readwise_export_highlights({
  payload = {
    updatedAfter = "2026-05-01T00:00:00Z",
    pageCursor = "cursor-from-previous-response"
  }
})
```

The raw `readwise_api_get`, `readwise_api_post`, `readwise_api_patch`, and `readwise_api_delete` tools only accept relative paths such as `/api/v3/list/`; full URLs are rejected.
Metadata-derived Lua example 
local result = app.integrations.readwise.check_auth({})
print(result)

Functions

check_auth Read

Validate the Readwise access token.

Lua path
app.integrations.readwise.check_auth
Full name
readwise.readwise_check_auth
ParameterTypeRequiredDescription
No parameters.
list_books Read

List Readwise books.

Lua path
app.integrations.readwise.list_books
Full name
readwise.readwise_list_books
ParameterTypeRequiredDescription
No parameters.
get_book Read

Get one Readwise book.

Lua path
app.integrations.readwise.get_book
Full name
readwise.readwise_get_book
ParameterTypeRequiredDescription
No parameters.
list_book_tags Read

List tags for a Readwise book.

Lua path
app.integrations.readwise.list_book_tags
Full name
readwise.readwise_list_book_tags
ParameterTypeRequiredDescription
No parameters.
create_book_tag Write

Create a tag on a Readwise book.

Lua path
app.integrations.readwise.create_book_tag
Full name
readwise.readwise_create_book_tag
ParameterTypeRequiredDescription
No parameters.
delete_book_tag Write

Delete a tag from a Readwise book.

Lua path
app.integrations.readwise.delete_book_tag
Full name
readwise.readwise_delete_book_tag
ParameterTypeRequiredDescription
No parameters.
list_highlights Read

List Readwise highlights.

Lua path
app.integrations.readwise.list_highlights
Full name
readwise.readwise_list_highlights
ParameterTypeRequiredDescription
No parameters.
create_highlights Write

Create one or more Readwise highlights.

Lua path
app.integrations.readwise.create_highlights
Full name
readwise.readwise_create_highlights
ParameterTypeRequiredDescription
No parameters.
get_highlight Read

Get one Readwise highlight.

Lua path
app.integrations.readwise.get_highlight
Full name
readwise.readwise_get_highlight
ParameterTypeRequiredDescription
No parameters.
update_highlight Write

Update a Readwise highlight.

Lua path
app.integrations.readwise.update_highlight
Full name
readwise.readwise_update_highlight
ParameterTypeRequiredDescription
No parameters.
delete_highlight Write

Delete a Readwise highlight.

Lua path
app.integrations.readwise.delete_highlight
Full name
readwise.readwise_delete_highlight
ParameterTypeRequiredDescription
No parameters.
list_highlight_tags Read

List tags for a highlight.

Lua path
app.integrations.readwise.list_highlight_tags
Full name
readwise.readwise_list_highlight_tags
ParameterTypeRequiredDescription
No parameters.
create_highlight_tag Write

Create a tag on a highlight.

Lua path
app.integrations.readwise.create_highlight_tag
Full name
readwise.readwise_create_highlight_tag
ParameterTypeRequiredDescription
No parameters.
delete_highlight_tag Write

Delete a tag from a highlight.

Lua path
app.integrations.readwise.delete_highlight_tag
Full name
readwise.readwise_delete_highlight_tag
ParameterTypeRequiredDescription
No parameters.
export_highlights Read

Sync Readwise export data.

Lua path
app.integrations.readwise.export_highlights
Full name
readwise.readwise_export_highlights
ParameterTypeRequiredDescription
No parameters.
get_review_queue Read

Get daily review queue items.

Lua path
app.integrations.readwise.get_review_queue
Full name
readwise.readwise_get_review_queue
ParameterTypeRequiredDescription
No parameters.
list_reader_documents Read

List Reader documents.

Lua path
app.integrations.readwise.list_reader_documents
Full name
readwise.readwise_list_documents
ParameterTypeRequiredDescription
No parameters.
save_reader_document Write

Save a document to Reader.

Lua path
app.integrations.readwise.save_reader_document
Full name
readwise.readwise_save_document
ParameterTypeRequiredDescription
No parameters.
update_reader_document Write

Update a Reader document.

Lua path
app.integrations.readwise.update_reader_document
Full name
readwise.readwise_update_document
ParameterTypeRequiredDescription
No parameters.
bulk_update_documents Write

Bulk update Reader documents.

Lua path
app.integrations.readwise.bulk_update_documents
Full name
readwise.readwise_bulk_update_documents
ParameterTypeRequiredDescription
No parameters.
delete_reader_document Write

Delete a Reader document.

Lua path
app.integrations.readwise.delete_reader_document
Full name
readwise.readwise_delete_document
ParameterTypeRequiredDescription
No parameters.
list_reader_tags Read

List Reader tags.

Lua path
app.integrations.readwise.list_reader_tags
Full name
readwise.readwise_list_reader_tags
ParameterTypeRequiredDescription
No parameters.
api_get Read

Call a safe relative Readwise GET path.

Lua path
app.integrations.readwise.api_get
Full name
readwise.readwise_api_get
ParameterTypeRequiredDescription
No parameters.
api_post Write

Call a safe relative Readwise POST path.

Lua path
app.integrations.readwise.api_post
Full name
readwise.readwise_api_post
ParameterTypeRequiredDescription
No parameters.
api_patch Write

Call a safe relative Readwise PATCH path.

Lua path
app.integrations.readwise.api_patch
Full name
readwise.readwise_api_patch
ParameterTypeRequiredDescription
No parameters.
api_delete Write

Call a safe relative Readwise DELETE path.

Lua path
app.integrations.readwise.api_delete
Full name
readwise.readwise_api_delete
ParameterTypeRequiredDescription
No parameters.