tech.waow.typeahead.searchActors Documentation (EN)

main query

Prefix search for atproto actors, ordered for typeahead use. Served entirely from a community-run index (https://typeahead.waow.tech); unauthenticated, CORS-enabled, results edge-cached for 60s. Also served at app.bsky.actor.searchActorsTypeahead as a drop-in migration alias with an identical response.

Parameters

limit integer Optional

Maximum number of actors to return.

pds string Optional

Optional exact hosting PDS hostname, e.g. acme.com. Case-insensitive; HTTP(S) origin and trailing slash/dot accepted, ports and paths rejected. Filters before candidate selection, including custom-domain handles. Scopes cover PDSs with at most 10,000 known actors at build time (configurable). Unknown PDS returns no actors; larger PDSs or unavailable scope support return HTTP 503 PdsScopeUnavailable.

q string Required

Search prefix; matched case-insensitively against handles and display names (CJK display names are matched via bigrams).

Output

Encodingapplication/json

actors array Required

Matching actors, best match first. Ranking blends prefix quality with a stored popularity score; actors hidden by moderation are excluded.

Errors

PdsScopeUnavailable PDS-scoped search is not available on the current backend or snapshot.

Try It

Requests are sent directly from your browser. Some servers may block requests due to CORS.

Service Endpoint Base URL for XRPC calls (e.g., https://api.bsky.social)

Parameters

limit Maximum number of actors to return.

pds Optional exact hosting PDS hostname, e.g. acme.com. Case-insensitive; HTTP(S) origin and trailing slash/dot accepted, ports and paths rejected. Filters before candidate selection, including custom-domain handles. Scopes cover PDSs with at most 10,000 known actors at build time (configurable). Unknown PDS returns no actors; larger PDSs or unavailable scope support return HTTP 503 PdsScopeUnavailable.

q * Search prefix; matched case-insensitively against handles and display names (CJK display names are matched via bigrams).

View raw schema

{
  "description": "Prefix search for atproto actors, ordered for typeahead use. Served entirely from a community-run index (https://typeahead.waow.tech); unauthenticated, CORS-enabled, results edge-cached for 60s. Also served at app.bsky.actor.searchActorsTypeahead as a drop-in migration alias with an identical response.",
  "errors": [
    {
      "description": "PDS-scoped search is not available on the current backend or snapshot.",
      "name": "PdsScopeUnavailable"
    }
  ],
  "output": {
    "encoding": "application/json",
    "schema": {
      "properties": {
        "actors": {
          "description": "Matching actors, best match first. Ranking blends prefix quality with a stored popularity score; actors hidden by moderation are excluded.",
          "items": {
            "ref": "#actorBasic",
            "type": "ref"
          },
          "type": "array"
        }
      },
      "required": [
        "actors"
      ],
      "type": "object"
    }
  },
  "parameters": {
    "properties": {
      "limit": {
        "default": 10,
        "description": "Maximum number of actors to return.",
        "maximum": 100,
        "minimum": 1,
        "type": "integer"
      },
      "pds": {
        "description": "Optional exact hosting PDS hostname, e.g. acme.com. Case-insensitive; HTTP(S) origin and trailing slash/dot accepted, ports and paths rejected. Filters before candidate selection, including custom-domain handles. Scopes cover PDSs with at most 10,000 known actors at build time (configurable). Unknown PDS returns no actors; larger PDSs or unavailable scope support return HTTP 503 PdsScopeUnavailable.",
        "type": "string"
      },
      "q": {
        "description": "Search prefix; matched case-insensitively against handles and display names (CJK display names are matched via bigrams).",
        "type": "string"
      }
    },
    "required": [
      "q"
    ],
    "type": "params"
  },
  "type": "query"
}

actorBasic object

2 examples

Basic actor profile. Matches the shape of app.bsky.actor.defs#profileViewBasic minus the authenticated viewer state, so results are interchangeable with bluesky's for unauthenticated use.

Properties

associated unknown Optional

Pass-through of app.bsky.actor.defs#profileAssociated as last seen from the actor's profile (lists, feedgens, starter packs, chat settings); absent if never observed.

avatar string uri Optional

Avatar image URL — usually a bluesky CDN URL, but may point directly at the actor's PDS blob endpoint for accounts bluesky's CDN no longer serves.

createdAt string datetime Optional

Account creation time as reported by the actor's profile view; absent if unknown.

did string did Required

The actor's decentralized identifier.

displayName string Optional

Self-declared display name from the actor's profile record; absent if unset.

maxLength: 640 bytesmaxGraphemes: 64 graphemes

handle string handle Required

The actor's current handle, e.g. zzstoatzz.io.

labels unknown Optional

Pass-through of the actor's com.atproto.label.defs#label array (self-labels and moderation-service labels) as last seen; may be empty.

View raw schema

{
  "description": "Basic actor profile. Matches the shape of app.bsky.actor.defs#profileViewBasic minus the authenticated viewer state, so results are interchangeable with bluesky's for unauthenticated use.",
  "properties": {
    "associated": {
      "description": "Pass-through of app.bsky.actor.defs#profileAssociated as last seen from the actor's profile (lists, feedgens, starter packs, chat settings); absent if never observed.",
      "type": "unknown"
    },
    "avatar": {
      "description": "Avatar image URL — usually a bluesky CDN URL, but may point directly at the actor's PDS blob endpoint for accounts bluesky's CDN no longer serves.",
      "format": "uri",
      "type": "string"
    },
    "createdAt": {
      "description": "Account creation time as reported by the actor's profile view; absent if unknown.",
      "format": "datetime",
      "type": "string"
    },
    "did": {
      "description": "The actor's decentralized identifier.",
      "format": "did",
      "type": "string"
    },
    "displayName": {
      "description": "Self-declared display name from the actor's profile record; absent if unset.",
      "maxGraphemes": 64,
      "maxLength": 640,
      "type": "string"
    },
    "handle": {
      "description": "The actor's current handle, e.g. zzstoatzz.io.",
      "format": "handle",
      "type": "string"
    },
    "labels": {
      "description": "Pass-through of the actor's com.atproto.label.defs#label array (self-labels and moderation-service labels) as last seen; may be empty.",
      "type": "unknown"
    }
  },
  "required": [
    "did",
    "handle"
  ],
  "type": "object"
}