> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nephia.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Bluesky

> What a keyword captures on Bluesky, and what arrives in each event.

## The post

Bluesky has one content unit, a **BlueskyPost**. `id` is the record key (`rkey`); `uri` is the global AT Protocol identity. `url` is the web link on `bsky.app`. Text, languages, author (handle + DID), metrics (likes, reposts, replies, quotes) and an optional embed (images, external link, record, video) travel together.

Do not call it a skeet in product language, and do not reuse **Post**: Reddit owns that envelope key.

## Coverage

A search on Bluesky requires a **search term and/or an author**: at least one must be set. Optional `lang` narrows a text search.

| Criterion | Values | Default |
| - | - | - |
| `author` | a handle (`alice.bsky.social`) | none |
| `lang` | a language code (`en`) | none |

These are this Source's own criteria: on the keyword they go in the search's `overrides.filters` (see [Keywords](/keywords#create)).

* With **author**, each tick polls that author's feed.
* With **query** (and no author), each tick polls post search, newest first.

Bluesky search operators work as-is: `from:handle`, `#tag`, `"exact phrase"`, and the rest of the grammar.

Interval: **120 to 86400** seconds. At most **20** active Bluesky searches per Account. Each tick costs **1 credit**.

## What an event carries

The first tick establishes a silent baseline and emits nothing. Later ticks emit `bluesky_post.created` with the full post in the `blueskyPost` envelope key. `webhookUrl` is optional: without it the keyword still records every match, readable through `GET /v1/keywords/{id}/events` in the same shape. See [Webhooks](/webhooks#replay).

```bash theme={null}
curl -X POST https://api.nephia.cc/v1/keywords \
  -H "x-api-key: $NEPHIA_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "name": "bsky.app posts",
    "refreshIntervalSeconds": 300,
    "globalCriteria": { "market": "global", "query": "from:bsky.app" },
    "sources": [
      {
        "source": "bluesky",
        "enabled": true,
        "searches": [
          {
            "overridesEnabled": true,
            "overrides": {
              "filters": {
                "lang": "en"
              }
            }
          }
        ]
      }
    ],
    "webhookUrl": "https://example.com/hooks/nephia"
  }'
```

Polling one author's feed instead:

```bash theme={null}
curl -X POST https://api.nephia.cc/v1/keywords \
  -H "x-api-key: $NEPHIA_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "name": "Jay on Bluesky",
    "refreshIntervalSeconds": 300,
    "globalCriteria": { "market": "global" },
    "sources": [
      {
        "source": "bluesky",
        "enabled": true,
        "searches": [
          {
            "overridesEnabled": true,
            "overrides": {
              "filters": {
                "author": "jay.bsky.team"
              }
            }
          }
        ]
      }
    ]
  }'
```

## Errors

A search whose author no longer resolves reports the failure in the keyword's activity rather than going quiet: read it through `GET /v1/keywords/{id}/activity`. A temporary Source failure is **503** and is not charged.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.