KosmoKrator

productivity

Pinboard Lua API for KosmoKrator Agents

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

Lua Namespace

Agents call this integration through app.integrations.pinboard.*. Use lua_read_doc("integrations.pinboard") 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 Pinboard workflow without starting an interactive agent session.

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

Workflow file

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

workflow.lua 
local pinboard = app.integrations.pinboard
local result = pinboard.posts_update({})

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.pinboard, app.mcp.*, docs.*, json.*, and regex.*. Use app.integrations.pinboard.default.* or app.integrations.pinboard.work.* when you configured named credential accounts.

MCP-only Lua

If the script only needs configured MCP servers and does not need Pinboard, 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.

Pinboard

Namespace: pinboard

Use this integration to manage Pinboard bookmarks, tags, user feed credentials, API tokens, and notes. Pinboard v1 uses auth_token in the query string and supports JSON responses through format=json, which this integration adds automatically.

Bookmarks

Add or update a bookmark:

pinboard_posts_add({
  url = "https://example.test/article",
  description = "Example Article",
  payload = {
    extended = "Short note",
    tags = "research examples",
    replace = "yes",
    shared = "no",
    toread = "yes"
  }
})

Read bookmarks:

pinboard_posts_recent({
  payload = {
    tag = "research",
    count = 25
  }
})

pinboard_posts_all({
  payload = {
    tag = "research",
    start = 0,
    results = 100,
    meta = "yes"
  }
})

Other bookmark tools:

  • pinboard_posts_update returns the latest add/update/delete timestamp.
  • pinboard_posts_get returns posts for a date or URL.
  • pinboard_posts_dates returns bookmark counts by date.
  • pinboard_posts_suggest returns popular and recommended tags for a URL.
  • pinboard_posts_delete deletes a bookmark by URL.

Tags

pinboard_tags_get({})

pinboard_tags_rename({
  old = "old-tag",
  new = "new-tag"
})

pinboard_tags_delete({ tag = "obsolete" })

User And Notes

pinboard_user_secret returns the secret RSS key. pinboard_user_api_token returns the API token for API calls without a password.

pinboard_notes_list({})

pinboard_notes_get({ note_id = "note:2a8a2ec9f3a076a1" })

Raw GET

pinboard_api_get calls a safe relative Pinboard v1 path and injects auth_token and format=json. It rejects absolute URLs.

pinboard_api_get({
  path = "/posts/recent",
  payload = {
    tag = "research",
    count = 10
  }
})
Raw agent markdown 
# Pinboard

Namespace: `pinboard`

Use this integration to manage Pinboard bookmarks, tags, user feed credentials, API tokens, and notes. Pinboard v1 uses `auth_token` in the query string and supports JSON responses through `format=json`, which this integration adds automatically.

## Bookmarks

Add or update a bookmark:

```lua
pinboard_posts_add({
  url = "https://example.test/article",
  description = "Example Article",
  payload = {
    extended = "Short note",
    tags = "research examples",
    replace = "yes",
    shared = "no",
    toread = "yes"
  }
})
```

Read bookmarks:

```lua
pinboard_posts_recent({
  payload = {
    tag = "research",
    count = 25
  }
})

pinboard_posts_all({
  payload = {
    tag = "research",
    start = 0,
    results = 100,
    meta = "yes"
  }
})
```

Other bookmark tools:

- `pinboard_posts_update` returns the latest add/update/delete timestamp.
- `pinboard_posts_get` returns posts for a date or URL.
- `pinboard_posts_dates` returns bookmark counts by date.
- `pinboard_posts_suggest` returns popular and recommended tags for a URL.
- `pinboard_posts_delete` deletes a bookmark by URL.

## Tags

```lua
pinboard_tags_get({})

pinboard_tags_rename({
  old = "old-tag",
  new = "new-tag"
})

pinboard_tags_delete({ tag = "obsolete" })
```

## User And Notes

`pinboard_user_secret` returns the secret RSS key. `pinboard_user_api_token` returns the API token for API calls without a password.

```lua
pinboard_notes_list({})

pinboard_notes_get({ note_id = "note:2a8a2ec9f3a076a1" })
```

## Raw GET

`pinboard_api_get` calls a safe relative Pinboard v1 path and injects `auth_token` and `format=json`. It rejects absolute URLs.

```lua
pinboard_api_get({
  path = "/posts/recent",
  payload = {
    tag = "research",
    count = 10
  }
})
```
Metadata-derived Lua example 
local result = app.integrations.pinboard.posts_update({})
print(result)

Functions

posts_update Read

Return the most recent bookmark add, update, or delete time.

Lua path
app.integrations.pinboard.posts_update
Full name
pinboard.pinboard_posts_update
ParameterTypeRequiredDescription
No parameters.
add_bookmark Write

Add or update a bookmark.

Lua path
app.integrations.pinboard.add_bookmark
Full name
pinboard.pinboard_posts_add
ParameterTypeRequiredDescription
No parameters.
delete_bookmark Write

Delete an existing bookmark.

Lua path
app.integrations.pinboard.delete_bookmark
Full name
pinboard.pinboard_posts_delete
ParameterTypeRequiredDescription
No parameters.
get_posts Read

Return one or more posts for a date or URL.

Lua path
app.integrations.pinboard.get_posts
Full name
pinboard.pinboard_posts_get
ParameterTypeRequiredDescription
No parameters.
recent_posts Read

Return recent posts, optionally filtered by tag.

Lua path
app.integrations.pinboard.recent_posts
Full name
pinboard.pinboard_posts_recent
ParameterTypeRequiredDescription
No parameters.
all_posts Read

Return all bookmarks in the account.

Lua path
app.integrations.pinboard.all_posts
Full name
pinboard.pinboard_posts_all
ParameterTypeRequiredDescription
No parameters.
post_dates Read

Return dates with bookmark counts.

Lua path
app.integrations.pinboard.post_dates
Full name
pinboard.pinboard_posts_dates
ParameterTypeRequiredDescription
No parameters.
suggest_tags Read

Return popular and recommended tags for a URL.

Lua path
app.integrations.pinboard.suggest_tags
Full name
pinboard.pinboard_posts_suggest
ParameterTypeRequiredDescription
No parameters.
get_tags Read

Return tags and usage counts.

Lua path
app.integrations.pinboard.get_tags
Full name
pinboard.pinboard_tags_get
ParameterTypeRequiredDescription
No parameters.
delete_tag Write

Delete all instances of a tag.

Lua path
app.integrations.pinboard.delete_tag
Full name
pinboard.pinboard_tags_delete
ParameterTypeRequiredDescription
No parameters.
rename_tag Write

Rename a tag or fold it into an existing tag.

Lua path
app.integrations.pinboard.rename_tag
Full name
pinboard.pinboard_tags_rename
ParameterTypeRequiredDescription
No parameters.
user_secret Read

Return the secret RSS key.

Lua path
app.integrations.pinboard.user_secret
Full name
pinboard.pinboard_user_secret
ParameterTypeRequiredDescription
No parameters.
api_token Read

Return the user API token.

Lua path
app.integrations.pinboard.api_token
Full name
pinboard.pinboard_user_api_token
ParameterTypeRequiredDescription
No parameters.
list_notes Read

Return a list of notes without note text detail.

Lua path
app.integrations.pinboard.list_notes
Full name
pinboard.pinboard_notes_list
ParameterTypeRequiredDescription
No parameters.
get_note Read

Return an individual note.

Lua path
app.integrations.pinboard.get_note
Full name
pinboard.pinboard_notes_get
ParameterTypeRequiredDescription
No parameters.
api_get Read

Call a safe relative Pinboard GET path for endpoints not covered by first-class tools.

Lua path
app.integrations.pinboard.api_get
Full name
pinboard.pinboard_api_get
ParameterTypeRequiredDescription
path string yes Relative Pinboard API path.
payload object no Query parameters.