Posts

Search

search-service

Finding posts, profiles and custom feeds by their words.

Search

GET/search/

Posts, profiles and custom feeds whose words match, of those the viewer may see. Search applies a post's audience and its profile's, but not the exceptions that let a profile's owner and a post's author see their own (permissions.md), so it may not find one's own restricted posts. Each person, group and event found says how it stands with the viewer, and each event when it is.

Who: Anyone, signed in or not

Parameters

startintegerin query
How many to pass over. At least 0.
limitintegerin query
The most to send. At least 0. 20 unless given.
sortstringin query
The order: the most relevant first, or the latest. At most 15 characters. One of relevant, recent. recent unless given.
dirstringin query
Which way the order runs. At most 4 characters. One of asc, desc. desc unless given.
termstringrequiredin query
The words looked for. At most 100 characters.
scopestringin query
What is looked among: everything, posts of every kind, photos and videos alone (media), profiles, or custom feeds. At most 20 characters. One of all, posts, media, actors, feeds. all unless given.
search_rangeintegerin query
How far from coord_lat and coord_lng, in metres, when both are given.
coord_lngnumberin query
Where to search near: longitude.
coord_latnumberin query
Where to search near: latitude.
followed_firstbooleanin query
The searcher's own choices for "Most relevant": people and groups they follow first, and interest that fades within a month.
recent_firstbooleanin query

Answers

200
OK
object application/json
400
the request is not well formed, or a value in it is not one it may be

Request

curl "https://api.example.org/search/?term=<term>"

const response = await fetch('https://api.example.org/search/?term=<term>', {
  method: 'GET',
});
const answer = await response.json();

import requests

response = requests.get(
    "https://api.example.org/search/?term=<term>",
)
answer = response.json()

Answer · 200

{
  "data": [
    {
      "access": "string",
      "alias": "string",
      "author": {
        "alias": null,
        "avatar_urls": null,
        "id": null,
        "name": null,
        "type": null
      },
      "authorized": {
        "add_follower": null,
        "administration": null,
        "audiences": null,
        "block_from_owner": null,
        "comment": null,
        "composers": null,
        "delete": null,
        "download": null,
        "edit": null,
        "hide": null,
        "invite": null,
        "like": null,
        "pin": null,
        "quote": null
      },
      "avatar_urls": {
        "key": null
      },
      "body": "string",
      "comment_count": 1,
      "content": "string",
      "cover_urls": {
        "key": null
      },
      "created_at": "2026-10-27T09:30:00Z",
      "editor": {
        "alias": null,
        "avatar_urls": null,
        "id": null,
        "name": null,
        "type": null
      },
      "event": {
        "address": null,
        "cancelled_at": null,
        "capacity": null,
        "ends_at": null,
        "going_count": null,
        "has_address": null,
        "has_online_url": null,
        "host": null,
        "is_full": null,
        "maybe_count": null,
        "online_url": null,
        "open_to_host_followers": null,
        "starts_at": null,
        "state": null,
        "timezone_name": null,
        "viewer_rsvp": null
      },
      "feed": {
        "definition": null,
        "icon": null
      },
      "files": [
        null
      ],
      "follower_count": 1,
      "id": 42,
      "is_admined_by_viewer": false,
      "is_blocked_by_viewer": false,
      "is_following_viewer": false,
      "is_leading_viewer": false,
      "is_liked_by_viewer": false,
      "is_reposted_by_viewer": false,
      "is_saved_by_viewer": false,
      "is_subscribed_by_viewer": false,
      "language": "en",
      "likes_count": 1,
      "link_preview": {
        "description": null,
        "image": null,
        "site_name": null,
        "title": null,
        "url": null
      },
      "media_removed": {
        "alts": null,
        "count": null,
        "gone": null
      },
      "mimetype": "string",
      "name": "string",
      "origin_domain": "string",
      "owner": {
        "alias": null,
        "avatar_urls": null,
        "body": null,
        "id": null,
        "is_following_viewer": null,
        "is_leading_viewer": null,
        "name": null,
        "type": null
      },
      "parent": {
        "access": null,
        "alias": null,
        "author": null,
        "authorized": null,
        "body": null,
        "content": null,
        "cover_urls": null,
        "created_at": null,
        "files": null,
        "id": null,
        "is_liked_by_viewer": null,
        "is_reposted_by_viewer": null,
        "is_saved_by_viewer": null,
        "link_preview": null,
        "name": null,
        "owner": null,
        "portrait_urls": null,
        "title": null,
        "type": null,
        "video": null
      },
      "pinned": false,
      "portrait_urls": {
        "key": null
      },
      "quote": {
        "post": null,
        "state": null
      },
      "quote_count": 1,
      "quote_id": 42,
      "repost_count": 1,
      "root": {
        "access": null,
        "alias": null,
        "author": null,
        "authorized": null,
        "body": null,
        "content": null,
        "cover_urls": null,
        "created_at": null,
        "files": null,
        "id": null,
        "is_liked_by_viewer": null,
        "is_reposted_by_viewer": null,
        "is_saved_by_viewer": null,
        "link_preview": null,
        "name": null,
        "owner": null,
        "portrait_urls": null,
        "title": null,
        "type": null,
        "video": null
      },
      "root_id": 42,
      "title": "string",
      "type": "string",
      "uri": "https://example.org/",
      "verified": false,
      "video": {
        "duration": null,
        "files": null,
        "height": null,
        "loop": null,
        "poster": null,
        "width": null
      }
    }
  ],
  "pagination": {
    "limit": 1,
    "offset": 1,
    "total": 1
  }
}

The viewer's weights for Most relevant

GET/search/preferences

How much each sign that something was found useful counts for the viewer: a step that multiplies the installation's own weight (search.md).

Who: Somebody signed in

Answers

200
OK
search.PreferencesResponse application/json
401
no token, or one that has expired

Request

curl "https://api.example.org/search/preferences" \
  -H "Authorization: Bearer $TOKEN"

const response = await fetch('https://api.example.org/search/preferences', {
  method: 'GET',
  headers: { Authorization: `Bearer ${token}` },
});
const answer = await response.json();

import requests

response = requests.get(
    "https://api.example.org/search/preferences",
    headers={"Authorization": f"Bearer {token}"},
)
answer = response.json()

Answer · 200

{
  "adjustable": [
    "string"
  ],
  "options": [
    1.5
  ],
  "steps": {
    "key": 1.5
  }
}

Change the viewer's weights for Most relevant

PUT/search/preferences

What is sent replaces what there was; a name left out is as the installation has it. Answers with them.

Who: Somebody signed in

Body application/json

stepsmap of number

Answers

200
OK
search.PreferencesResponse application/json
400
the request is not well formed, or a value in it is not one it may be
401
no token, or one that has expired
422
invalid_weight: a name that may not be set, or a value that is not a step; nothing is changed
Refusal application/json

Request

curl -X PUT "https://api.example.org/search/preferences" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "steps": {
      "key": 1.5
    }
  }'

const response = await fetch('https://api.example.org/search/preferences', {
  method: 'PUT',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "steps": {
      "key": 1.5
    }
  }),
});
const answer = await response.json();

import requests

response = requests.put(
    "https://api.example.org/search/preferences",
    headers={"Authorization": f"Bearer {token}"},
    json={
      "steps": {
        "key": 1.5
      }
    },
)
answer = response.json()

Answer · 200

{
  "adjustable": [
    "string"
  ],
  "options": [
    1.5
  ],
  "steps": {
    "key": 1.5
  }
}

Written by Claude, reviewed by Rastin Mehr · About this