Search actors

GET

/api/v1/search/actor

curl --request GET \
  --url 'https://example.com/api/v1/search/actor?q=example&limit=3&includeSelf=true'

Searches for ActivityPub actors by username. If the query is a valid federated handle (e.g. user@domain.tld), it attempts a direct ActivityPub lookup first and returns that result immediately. If the handle lookup fails, or if the query is not a handle, it falls back to a local Meilisearch index query. Returns a Meilisearch-shaped SearchResponse in both cases.

Parameters

Query Parameters

q

required

string

Search query. Can be a plain username substring or a fully-qualified ActivityPub handle (user@domain.tld). Handles trigger a federated lookup before falling back to local search.

limit

integer

default: 3

Maximum number of results to return from the local index. Has no effect when a federated handle is resolved successfully (always returns exactly one hit).

includeSelf

boolean

default: true

When false and the request is authenticated, the authenticated user’s own actor is excluded from local search results.

Responses

200

Meilisearch-shaped response containing matching actors. The hits array contains actor objects with id, domain, is_local, preferred_username, username, and icon fields.

Media typeapplication/json

object

hits

Array<object>

object

id

string

domain

string

is_local

boolean

preferred_username

string

username

string

icon

string

query

string

processingTimeMs

integer

estimatedTotalHits

integer

totalHits

integer

totalPages

integer

page

integer

Example^generated

{
  "hits": [
    {
      "id": "example",
      "domain": "example",
      "is_local": true,
      "preferred_username": "example",
      "username": "example",
      "icon": "example"
    }
  ],
  "query": "example",
  "processingTimeMs": 1,
  "estimatedTotalHits": 1,
  "totalHits": 1,
  "totalPages": 1,
  "page": 1
}

400

Missing required q parameter.

404

Federated fetch failed with a network error.

500

Internal server error.