People

Recommendations

recommendation-service

Who the viewer might follow, with the reasons, worked out from the graph by rules and no model; and the viewer's own choices about it. Optional: an installation may not run it, or may run another service that answers these routes (recommendations.md).

Who the viewer might follow

GET/recommendations/actors

People, groups and events, best first, each with why. Nobody the viewer follows already, nobody on either side of a block with them, nobody they dismissed, and nobody who asked not to be suggested: the whole list is under Who is never suggested in recommendations.md.

Who: Somebody signed in

Parameters

kindstringin query
Only people, only groups, or only events. All of them when left out. One of person, group, event.
contextstringin query
home (the default), or onboarding for somebody who has just joined and follows nobody: nothing worked out from who they follow is used. One of home, onboarding.
limitintegerin query
The most to send: up to 50, 10 when left out. At least 1. At most 50.

Answers

200
OK
recommendation.ActorsResponse 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

Request

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

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

import requests

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

Answer · 200

{
  "items": [
    {
      "actor": null,
      "actor_id": 42,
      "reasons": [
        null
      ],
      "score": 1.5
    }
  ],
  "related": [
    {
      "alias": "string",
      "avatar_urls": {
        "key": null
      },
      "id": 42,
      "name": "string",
      "type": "string",
      "verified": false
    }
  ]
}

Whom the viewer is not interested in

GET/recommendations/dismissals

Who: Somebody signed in

Answers

200
OK
object application/json
401
no token, or one that has expired

Request

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

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

import requests

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

Answer · 200

{
  "data": [
    {
      "alias": "string",
      "avatar_urls": {
        "key": null
      },
      "id": 42,
      "name": "string",
      "type": "string",
      "verified": false
    }
  ]
}

Not interested in this one

POST/recommendations/dismissals

They are not suggested to the viewer again.

Who: Somebody signed in

Body application/json

actor_idintegerrequired
The id of the profile the viewer is not interested in. At least 1.

Answers

204
done
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

Request

curl -X POST "https://api.example.org/recommendations/dismissals" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "actor_id": 42
  }'

const response = await fetch('https://api.example.org/recommendations/dismissals', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "actor_id": 42
  }),
});
const answer = await response.json();

import requests

response = requests.post(
    "https://api.example.org/recommendations/dismissals",
    headers={"Authorization": f"Bearer {token}"},
    json={
      "actor_id": 42
    },
)
answer = response.json()

Take that back

DELETE/recommendations/dismissals/{actor_id}

Who: Somebody signed in

Parameters

actor_idintegerrequiredin path
The id of the profile. At least 1.

Answers

204
done
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

Request

curl -X DELETE "https://api.example.org/recommendations/dismissals/<actor_id>" \
  -H "Authorization: Bearer $TOKEN"

const response = await fetch('https://api.example.org/recommendations/dismissals/<actor_id>', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${token}` },
});
const answer = await response.json();

import requests

response = requests.delete(
    "https://api.example.org/recommendations/dismissals/<actor_id>",
    headers={"Authorization": f"Bearer {token}"},
)
answer = response.json()

Hashtags to pick from when signing up

GET/recommendations/interests

The ones on the most public posts lately, the most used first, looking further back until enough are found: the last three months, then the year, then all of it.

Who: Somebody signed in

Parameters

limitintegerin query
The most to send: 20 unless asked, 40 at most. At least 1. At most 40.

Answers

200
OK
object 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

Request

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

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

import requests

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

Answer · 200

{
  "data": [
    {
      "alias": "string",
      "count": 1,
      "id": 42,
      "name": "string"
    }
  ]
}

The viewer's choices

GET/recommendations/preferences

Who: Somebody signed in

Answers

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

Request

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

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

import requests

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

Answer · 200

{
  "active_within_choices": [
    1
  ],
  "active_within_days": 1,
  "active_within_default": 1,
  "default_weights": {
    "key": 1.5
  },
  "discoverable": false,
  "max_weight": 1.5,
  "reasons": [
    "string"
  ],
  "suggest_events": false,
  "suggest_groups": false,
  "suggest_people": false,
  "use_activity": false,
  "weights": {
    "key": 1.5
  }
}

Change the viewer's choices

PUT/recommendations/preferences

What is sent is set, and what is left out is left as it is. Answers with them all.

Who: Somebody signed in

Body application/json

active_within_daysinteger
How lately somebody must have been here to be suggested, in days: one of constants.ActiveWithinChoices.
discoverableboolean
That they may be suggested to other people.
reset_weightsboolean
Back to the service's own weights, and its own limit on how lately somebody was here. Before any sent with it.
suggest_eventsboolean
To be suggested events.
suggest_groupsboolean
To be suggested groups.
suggest_peopleboolean
To be suggested people.
use_activityboolean
That what they liked and wrote may be used to choose for them.
weightsmap of number
How much each reason counts for, by its name: 0, which turns the reason off, to constants.MaxWeight. The ones sent are set and the others left.

Answers

200
OK
recommendation.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 reason there is not, or a weight out of range; nothing is changed
Refusal application/json

Request

curl -X PUT "https://api.example.org/recommendations/preferences" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "active_within_days": 1,
    "discoverable": false,
    "reset_weights": false,
    "suggest_events": false,
    "suggest_groups": false,
    "suggest_people": false,
    "use_activity": false,
    "weights": {
      "key": 1.5
    }
  }'

const response = await fetch('https://api.example.org/recommendations/preferences', {
  method: 'PUT',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    "active_within_days": 1,
    "discoverable": false,
    "reset_weights": false,
    "suggest_events": false,
    "suggest_groups": false,
    "suggest_people": false,
    "use_activity": false,
    "weights": {
      "key": 1.5
    }
  }),
});
const answer = await response.json();

import requests

response = requests.put(
    "https://api.example.org/recommendations/preferences",
    headers={"Authorization": f"Bearer {token}"},
    json={
      "active_within_days": 1,
      "discoverable": False,
      "reset_weights": False,
      "suggest_events": False,
      "suggest_groups": False,
      "suggest_people": False,
      "use_activity": False,
      "weights": {
        "key": 1.5
      }
    },
)
answer = response.json()

Answer · 200

{
  "active_within_choices": [
    1
  ],
  "active_within_days": 1,
  "active_within_default": 1,
  "default_weights": {
    "key": 1.5
  },
  "discoverable": false,
  "max_weight": 1.5,
  "reasons": [
    "string"
  ],
  "suggest_events": false,
  "suggest_groups": false,
  "suggest_people": false,
  "use_activity": false,
  "weights": {
    "key": 1.5
  }
}

Written by Claude, reviewed by Rastin Mehr · About this