Clearsky Services API

This service provides raw and aggregated information from Bluesky using ATProto.

Issues

If you encounter any issues or have suggestions for improvements, please open an issue ticket on our GitHub repository.

Table of contents

• v2 Usage
• v1 Usage

Usage

See the latest API Documentation for more information on the available endpoints.

Announcements

Ongoing:

• We are working to finalize v2 of the API, you may see changes as we update responses.
  • NOTE: Some changes will be announced before implemented and others will not.
• Some endpoints listed in this documentation may be disabled.
• Validating error responses.

11/12/2025:

• v1 of the API has been finalized.
• v2 will be available to use soon.
• v2 contains the new pagination and query params implementation.
• v1 will remain available to use until 06/01/2026.
• We will be publishing the v2 documentation very soon.

11/1/2025:

The new hostname public.api.clearsky.services is now live! You can start using it right away. To allow for a smooth transition, the old hostname will remain functional for 2 weeks, until 11/16/2025 at 6pm pacific time.

10/28/2025:

A new API hostname will be introduced soon: public.api.clearsky.services

Once the new hostname is live, both the existing and new hostnames will function simultaneously for a transition period, afterward, the old services will be unavailable. We will announce when the new hostname is live.

10/23/2025:

We will be updating how params are sent to the API. The changes will be as follows:

• All endpoints will be converted to use query parameters for GET requests

Example:

Old:

```GET /api/v1/anon/blocklist/{identifier}```

New:

```GET /api/v1/anon/blocklist?identifier={identifier}```

This change will roll out with the new pagination changes.

10/20/2025:

We will be updating how pagination functions across the API. The changes will be as follows:

• All endpoints that support pagination will now use a consistent approach with limit and cursor parameters.
• The limit parameter will define the maximum number of items to return. For now, the maximum limit will be the default limit and cannot be increased.
• The cursor parameter will be used to fetch the next set of results based on the last item of the previous response.
• The response will include a cursor field if there are more results to fetch.
• This change aims to simplify pagination and make it more predictable across all endpoints.
• We will announce when these changes go live.

10/18/2025:

Error responses have been updated to the new format.

10/16/2025:

We will be updating error responses very soon. The format will be changing to be more standardized.

example:

{
    "status": 401,
    "error_type": "Unauthorized",
    "message": "Unauthorized: Authentication credentials are missing or invalid."
}

{
    "status": 401,
    "error_type": "Unauthorized",
    "message": "Unauthorized: Authentication credentials are missing or invalid.",
    "details": {
        "authenticated": false,
        "identifier": "thieflord.dev",
        "error": "Unauthorized"
    }
}

{
    "status": 500,
    "error_type": "InternalServerError",
    "message": "An unexpected error occurred on the server.",
    "details": "Failed to load record"
}