KosmoKrator

social

Bluesky Lua API for KosmoKrator Agents

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

6 functions 5 read 1 write Manual OAuth token auth
Submit Bluesky feedback View package source

Lua Namespace

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

Agent-Facing Lua Docs

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

Bluesky — Lua API Reference

create_post

Create a new post on Bluesky.

Parameters

NameTypeRequiredDescription
textstringyesPost text (max 300 graphemes)
langsarraynoBCP-47 language tags, e.g. {"en", "nl"}
facetsarraynoRich-text facets (mentions, links, tags)
createdAtstringnoISO 8601 timestamp (defaults to now)

Examples

-- Simple text post
local result = app.integrations.bluesky.create_post({
  text = "Hello from the integration!"
})
print("Post URI: " .. result.uri)

-- Post with language tags
local result = app.integrations.bluesky.create_post({
  text = "Hallo wereld!",
  langs = { "nl" }
})

get_profile

Get the public profile of a Bluesky user.

Parameters

NameTypeRequiredDescription
actorstringyesHandle (e.g. "alice.bsky.social") or DID

Examples

local profile = app.integrations.bluesky.get_profile({
  actor = "alice.bsky.social"
})
print(profile.displayName .. " has " .. profile.followersCount .. " followers")

list_followers

List followers of a Bluesky account.

Parameters

NameTypeRequiredDescription
actorstringyesHandle or DID
limitintegernoResults per page (1–100, default 50)
cursorstringnoPagination cursor from a previous response

Examples

local result = app.integrations.bluesky.list_followers({
  actor = "alice.bsky.social",
  limit = 10
})

for _, follower in ipairs(result.followers) do
  print(follower.handle .. " (" .. (follower.displayName or "no name") .. ")")
end

-- Paginate
if result.cursor then
  local next = app.integrations.bluesky.list_followers({
    actor = "alice.bsky.social",
    cursor = result.cursor
  })
end

list_following

List accounts that a Bluesky user follows.

Parameters

NameTypeRequiredDescription
actorstringyesHandle or DID
limitintegernoResults per page (1–100, default 50)
cursorstringnoPagination cursor from a previous response

Examples

local result = app.integrations.bluesky.list_following({
  actor = "alice.bsky.social",
  limit = 10
})

for _, follow in ipairs(result.follows) do
  print(follow.handle)
end

search_posts

Search for posts on the Bluesky network.

Parameters

NameTypeRequiredDescription
qstringyesSearch query
limitintegernoResults per page (1–100, default 25)
cursorstringnoPagination cursor from a previous response

Search Operators

  • "from:user.bsky.social" — posts from a specific user
  • "has:images" — posts containing images
  • "lang:en" — posts in a specific language
  • Boolean: "term1 term2" (AND), "term1 OR term2" (OR), "-term" (exclude)

Examples

-- Simple search
local result = app.integrations.bluesky.search_posts({
  q = "Laravel",
  limit = 5
})

for _, post in ipairs(result.posts) do
  print(post.author.handle .. ": " .. post.record.text)
end

-- Search with operators
local result = app.integrations.bluesky.search_posts({
  q = "from:alice.bsky.social PHP",
  limit = 10
})

get_current_user

Get the authenticated user’s own Bluesky profile. No parameters required.

Examples

local me = app.integrations.bluesky.get_current_user({})
print("Logged in as @" .. me.handle)
print("Display name: " .. (me.displayName or "not set"))
print("Followers: " .. me.followersCount)
print("Following: " .. me.followsCount)
print("Posts: " .. me.postsCount)

Multi-Account Usage

If you have multiple Bluesky accounts configured, use account-specific namespaces:

-- Default account (always works)
app.integrations.bluesky.create_post({ text = "Hello!" })

-- Explicit default (portable across setups)
app.integrations.bluesky.default.create_post({ text = "Hello!" })

-- Named accounts
app.integrations.bluesky.work.create_post({ text = "Work update" })
app.integrations.bluesky.personal.search_posts({ q = "hobbies" })

All functions are identical across accounts — only the credentials differ.

Raw agent markdown 
# Bluesky — Lua API Reference

## create_post

Create a new post on Bluesky.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `text` | string | yes | Post text (max 300 graphemes) |
| `langs` | array | no | BCP-47 language tags, e.g. `{"en", "nl"}` |
| `facets` | array | no | Rich-text facets (mentions, links, tags) |
| `createdAt` | string | no | ISO 8601 timestamp (defaults to now) |

### Examples

```lua
-- Simple text post
local result = app.integrations.bluesky.create_post({
  text = "Hello from the integration!"
})
print("Post URI: " .. result.uri)

-- Post with language tags
local result = app.integrations.bluesky.create_post({
  text = "Hallo wereld!",
  langs = { "nl" }
})
```

---

## get_profile

Get the public profile of a Bluesky user.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `actor` | string | yes | Handle (e.g. `"alice.bsky.social"`) or DID |

### Examples

```lua
local profile = app.integrations.bluesky.get_profile({
  actor = "alice.bsky.social"
})
print(profile.displayName .. " has " .. profile.followersCount .. " followers")
```

---

## list_followers

List followers of a Bluesky account.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `actor` | string | yes | Handle or DID |
| `limit` | integer | no | Results per page (1–100, default 50) |
| `cursor` | string | no | Pagination cursor from a previous response |

### Examples

```lua
local result = app.integrations.bluesky.list_followers({
  actor = "alice.bsky.social",
  limit = 10
})

for _, follower in ipairs(result.followers) do
  print(follower.handle .. " (" .. (follower.displayName or "no name") .. ")")
end

-- Paginate
if result.cursor then
  local next = app.integrations.bluesky.list_followers({
    actor = "alice.bsky.social",
    cursor = result.cursor
  })
end
```

---

## list_following

List accounts that a Bluesky user follows.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `actor` | string | yes | Handle or DID |
| `limit` | integer | no | Results per page (1–100, default 50) |
| `cursor` | string | no | Pagination cursor from a previous response |

### Examples

```lua
local result = app.integrations.bluesky.list_following({
  actor = "alice.bsky.social",
  limit = 10
})

for _, follow in ipairs(result.follows) do
  print(follow.handle)
end
```

---

## search_posts

Search for posts on the Bluesky network.

### Parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `q` | string | yes | Search query |
| `limit` | integer | no | Results per page (1–100, default 25) |
| `cursor` | string | no | Pagination cursor from a previous response |

### Search Operators

- `"from:user.bsky.social"` — posts from a specific user
- `"has:images"` — posts containing images
- `"lang:en"` — posts in a specific language
- Boolean: `"term1 term2"` (AND), `"term1 OR term2"` (OR), `"-term"` (exclude)

### Examples

```lua
-- Simple search
local result = app.integrations.bluesky.search_posts({
  q = "Laravel",
  limit = 5
})

for _, post in ipairs(result.posts) do
  print(post.author.handle .. ": " .. post.record.text)
end

-- Search with operators
local result = app.integrations.bluesky.search_posts({
  q = "from:alice.bsky.social PHP",
  limit = 10
})
```

---

## get_current_user

Get the authenticated user's own Bluesky profile. No parameters required.

### Examples

```lua
local me = app.integrations.bluesky.get_current_user({})
print("Logged in as @" .. me.handle)
print("Display name: " .. (me.displayName or "not set"))
print("Followers: " .. me.followersCount)
print("Following: " .. me.followsCount)
print("Posts: " .. me.postsCount)
```

---

## Multi-Account Usage

If you have multiple Bluesky accounts configured, use account-specific namespaces:

```lua
-- Default account (always works)
app.integrations.bluesky.create_post({ text = "Hello!" })

-- Explicit default (portable across setups)
app.integrations.bluesky.default.create_post({ text = "Hello!" })

-- Named accounts
app.integrations.bluesky.work.create_post({ text = "Work update" })
app.integrations.bluesky.personal.search_posts({ q = "hobbies" })
```

All functions are identical across accounts — only the credentials differ.

Metadata-Derived Lua Example

local result = app.integrations.bluesky.bluesky_create_post({
  text = "example_text",
  langs = "example_langs",
  facets = "example_facets",
  createdAt = "example_createdAt"
})
print(result)

Functions

bluesky_create_post

Create a new post on Bluesky. The post text is required and supports facets (mentions, links, tags) if provided.

Operation
Write write
Full name
bluesky.bluesky_create_post
ParameterTypeRequiredDescription
text string yes The text content of the post (max 300 graphemes).
langs array no BCP-47 language tags (e.g. ["en", "nl"]). Defaults to ["en"].
facets array no Optional facets for rich text (mentions, links, tags). Each facet needs index.byteStart, index.byteEnd, and features array.
createdAt string no ISO 8601 timestamp. Defaults to now if omitted.

bluesky_get_profile

Get the public profile of a Bluesky user. Provide a handle (e.g. "alice.bsky.social") or DID.

Operation
Read read
Full name
bluesky.bluesky_get_profile
ParameterTypeRequiredDescription
actor string yes Handle (e.g. "alice.bsky.social") or DID (e.g. "did:plc:...").

bluesky_list_followers

List the followers of a Bluesky account. Returns follower profiles with handles, display names, and avatars.

Operation
Read read
Full name
bluesky.bluesky_list_followers
ParameterTypeRequiredDescription
actor string yes Handle or DID of the user whose followers to list.
limit integer no Number of results per page (1–100, default 50).
cursor string no Pagination cursor from a previous response to fetch the next page.

bluesky_list_following

List the accounts that a Bluesky user follows. Returns profiles with handles, display names, and avatars.

Operation
Read read
Full name
bluesky.bluesky_list_following
ParameterTypeRequiredDescription
actor string yes Handle or DID of the user whose follows to list.
limit integer no Number of results per page (1–100, default 50).
cursor string no Pagination cursor from a previous response to fetch the next page.

bluesky_search_posts

Search for posts on Bluesky. Supports full-text search queries. Returns matching posts with author, text, and timestamps.

Operation
Read read
Full name
bluesky.bluesky_search_posts
ParameterTypeRequiredDescription
q string yes Search query. Supports search operators like "from:user", "has:images", "lang:en", and boolean combinations.
limit integer no Number of results per page (1–100, default 25).
cursor string no Pagination cursor from a previous response to fetch the next page.

bluesky_get_current_user

Get the authenticated user's own Bluesky profile. No parameters required — uses the configured account.

Operation
Read read
Full name
bluesky.bluesky_get_current_user
ParameterTypeRequiredDescription
No parameters.