# SocialCrawl API: bluesky endpoints
# Base URL: https://www.socialcrawl.dev
# Auth: x-api-key header
# Full docs: https://www.socialcrawl.dev/docs/bluesky

## GET /v1/bluesky/profile
Get a Bluesky profile
Credit cost: 1 (standard)
Parameters:
- handle (required): Bluesky handle (e.g. `espn.com`).
curl -G "https://www.socialcrawl.dev/v1/bluesky/profile" \
  --data-urlencode "handle=espn.com" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/bluesky/user/posts
List a Bluesky user's posts
Credit cost: 1 (standard)
Parameters:
- handle (optional, string): Bluesky handle.
- user_id (optional, string): Bluesky `did` (Bluesky's internal user ID format, e.g. `did:plc:x7d6j54pm22ufehkes6jo4jf`).
- since (optional, string): Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`.
- until (optional, string): Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`.
- Constraint: one of handle, user_id (at least one required)
curl -G "https://www.socialcrawl.dev/v1/bluesky/user/posts" \
  --data-urlencode "handle=espn.com" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/bluesky/post
Get a Bluesky post
Credit cost: 1 (standard)
Parameters:
- url (required): Bluesky post URL.
curl -G "https://www.socialcrawl.dev/v1/bluesky/post" \
  --data-urlencode "url=https://bsky.app/profile/espn.com/post/3lqdfq7fkvm2g" \
  -H "x-api-key: YOUR_API_KEY"

## GET /v1/bluesky/search
Search Bluesky posts
Credit cost: 1 (standard)
Parameters:
- query (required): Search terms matched against post text.
- sort (optional, enum: latest | top): `latest` (newest first, the default) or `top` (Bluesky's own top ranking, which favours popular posts over recent ones).
- since (optional, string): Only posts written at or after this time. ISO 8601 date (`2026-09-01`) or datetime with a timezone (`2026-09-01T00:00:00Z`); any other shape is rejected with a free 400.
- until (optional, string): Only posts written before this time. Same format as `since`. Set it to the oldest `published_at` of your last call to fetch the next older batch; the boundary is compared to the second, so a post from that same second can repeat, and deduplicating on `post.id` removes it.
- lang (optional, string): Only posts tagged with this language, as a code such as `en`, `ja` or `ko`.
- author (optional, string): Only posts by this account: a handle such as `espn.com` or a `did` such as `did:plc:...`. An account that does not exist returns an empty list.
curl -G "https://www.socialcrawl.dev/v1/bluesky/search" \
  --data-urlencode "query=espresso" \
  -H "x-api-key: YOUR_API_KEY"