> ## 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 Nephia Watch on Bluesky captures, 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 Watch on Bluesky requires a **search term and/or an author** — at least one must be set. Optional `lang` narrows a search Watch.

* 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–86400** seconds. Cap: **20** active Watches 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. `webhook_url` is optional — without it the Watch still records every match, readable through `GET /v1/bluesky/watches/{id}/events`. See [Webhooks](/webhooks).

```bash theme={null}
curl -X POST https://api.nephia.cc/v1/bluesky/watches \
  -H "x-api-key: $NEPHIA_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "query": "from:bsky.app",
    "lang": "en",
    "refresh_interval_seconds": 300,
    "webhook_url": "https://example.com/hooks/nephia"
  }'
```

```bash theme={null}
curl -X POST https://api.nephia.cc/v1/bluesky/watches \
  -H "x-api-key: $NEPHIA_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "author": "jay.bsky.team",
    "refresh_interval_seconds": 300
  }'
```

## Errors

A Watch whose author no longer resolves reports the failure in its activity rather than going quiet — read it through `GET /v1/bluesky/watches/{id}/activity`. A temporary Source failure is **503** and is not charged.