us.off-the-clock.searchRecords Documentation (EN)

main query

Posts, events, bookmarks and polls of one content space the viewer reads, matching every condition given: words (keyword), a full-text query (text) or a meaning (semantic), an H3 cell, a radius around a point, a bookmark's domain and a tag. Only records the viewer may see are answered, never another space's. SearchUnavailable is answered for mode=semantic before any other parameter is read, so a call without q tells a client whether meaning search is on.

Parameters

collection string nsid Optional

Posts, events, bookmarks or polls; all four when absent.

cursor string Optional

No description available.

domain string Optional

Bookmarks whose subject's host is this domain or a subdomain of it, case-insensitive.

from string datetime Optional

Records sorted at or after this time.

h3 string Optional

An H3 cell index in hexadecimal, at resolution 4 to 10.

limit integer Optional

No description available.

mode string Optional

No description available.

near string Optional

A point as decimal degrees, latitude,longitude.

q string Optional

Required unless h3, near, domain or tag is given.

space string tid Required

The pair's TID.

tag string Optional

Bookmarks carrying this tag, case-insensitive.

until string datetime Optional

Records sorted before this time.

within string Optional

The radius around near in kilometres, a decimal from 0.1 to 100; 5 by default.

Output

Encodingapplication/json

cursor string Optional

No description available.

hits array Required

No description available.

mapUrl stringuri Optional

For a search by place: a signed map of this page's first ten hits, numbered in order (IMG-14), when a map provider is configured.

noPlaces boolean Optional

True on a search by place that found nothing in a space where no record has a place yet.

Errors

InvalidRequest

NotSpaceMember

SearchUnavailable mode=semantic on a site with no embeddings endpoint.

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

collection Posts, events, bookmarks or polls; all four when absent.

cursor

domain Bookmarks whose subject's host is this domain or a subdomain of it, case-insensitive.

from Records sorted at or after this time.

h3 An H3 cell index in hexadecimal, at resolution 4 to 10.

limit

mode

near A point as decimal degrees, latitude,longitude.

q Required unless h3, near, domain or tag is given.

space * The pair's TID.

tag Bookmarks carrying this tag, case-insensitive.

until Records sorted before this time.

within The radius around near in kilometres, a decimal from 0.1 to 100; 5 by default.

View raw schema

{
  "description": "Posts, events, bookmarks and polls of one content space the viewer reads, matching every condition given: words (keyword), a full-text query (text) or a meaning (semantic), an H3 cell, a radius around a point, a bookmark's domain and a tag. Only records the viewer may see are answered, never another space's. SearchUnavailable is answered for mode=semantic before any other parameter is read, so a call without q tells a client whether meaning search is on.",
  "errors": [
    {
      "name": "InvalidRequest"
    },
    {
      "name": "NotSpaceMember"
    },
    {
      "description": "mode=semantic on a site with no embeddings endpoint.",
      "name": "SearchUnavailable"
    }
  ],
  "output": {
    "encoding": "application/json",
    "schema": {
      "properties": {
        "cursor": {
          "type": "string"
        },
        "hits": {
          "items": {
            "ref": "#hit",
            "type": "ref"
          },
          "type": "array"
        },
        "mapUrl": {
          "description": "For a search by place: a signed map of this page's first ten hits, numbered in order (IMG-14), when a map provider is configured.",
          "format": "uri",
          "type": "string"
        },
        "noPlaces": {
          "description": "True on a search by place that found nothing in a space where no record has a place yet.",
          "type": "boolean"
        }
      },
      "required": [
        "hits"
      ],
      "type": "object"
    }
  },
  "parameters": {
    "properties": {
      "collection": {
        "description": "Posts, events, bookmarks or polls; all four when absent.",
        "format": "nsid",
        "knownValues": [
          "app.bsky.feed.post",
          "community.lexicon.calendar.event",
          "community.lexicon.bookmarks.bookmark",
          "us.off-the-clock.polls.poll"
        ],
        "type": "string"
      },
      "cursor": {
        "type": "string"
      },
      "domain": {
        "description": "Bookmarks whose subject's host is this domain or a subdomain of it, case-insensitive.",
        "maxLength": 253,
        "type": "string"
      },
      "from": {
        "description": "Records sorted at or after this time.",
        "format": "datetime",
        "type": "string"
      },
      "h3": {
        "description": "An H3 cell index in hexadecimal, at resolution 4 to 10.",
        "maxLength": 16,
        "type": "string"
      },
      "limit": {
        "default": 25,
        "maximum": 50,
        "minimum": 1,
        "type": "integer"
      },
      "mode": {
        "default": "keyword",
        "knownValues": [
          "keyword",
          "text",
          "semantic"
        ],
        "maxLength": 16,
        "type": "string"
      },
      "near": {
        "description": "A point as decimal degrees, latitude,longitude.",
        "maxLength": 64,
        "type": "string"
      },
      "q": {
        "description": "Required unless h3, near, domain or tag is given.",
        "maxLength": 200,
        "minLength": 1,
        "type": "string"
      },
      "space": {
        "description": "The pair's TID.",
        "format": "tid",
        "type": "string"
      },
      "tag": {
        "description": "Bookmarks carrying this tag, case-insensitive.",
        "maxLength": 64,
        "type": "string"
      },
      "until": {
        "description": "Records sorted before this time.",
        "format": "datetime",
        "type": "string"
      },
      "within": {
        "description": "The radius around near in kilometres, a decimal from 0.1 to 100; 5 by default.",
        "maxLength": 16,
        "type": "string"
      }
    },
    "required": [
      "space"
    ],
    "type": "params"
  },
  "type": "query"
}

hit object

No description available.

Properties

distanceKm string Optional

For near: the distance in kilometres from the point to the record's nearest place, a decimal.

maxLength: 16 bytes

record union Required

No description available.

Known types:

score string Required

The mode's own number as a decimal: BM25 made positive for keyword and text, cosine similarity for semantic, 0 for a search by place alone. Lexicons carry no floats.

maxLength: 32 bytes

snippet string Optional

The matched text with each match between [ and ].

maxLength: 2000 bytes

View raw schema

{
  "properties": {
    "distanceKm": {
      "description": "For near: the distance in kilometres from the point to the record's nearest place, a decimal.",
      "maxLength": 16,
      "type": "string"
    },
    "record": {
      "refs": [
        "us.off-the-clock.defs#postView",
        "us.off-the-clock.defs#eventView",
        "us.off-the-clock.defs#bookmarkView",
        "us.off-the-clock.polls.pollView"
      ],
      "type": "union"
    },
    "score": {
      "description": "The mode's own number as a decimal: BM25 made positive for keyword and text, cosine similarity for semantic, 0 for a search by place alone. Lexicons carry no floats.",
      "maxLength": 32,
      "type": "string"
    },
    "snippet": {
      "description": "The matched text with each match between [ and ].",
      "maxLength": 2000,
      "type": "string"
    }
  },
  "required": [
    "record",
    "score"
  ],
  "type": "object"
}