Instance

Instance Follows

Managing servers which the instance interacts with is crucial to the concept of federation in PeerTube and external video indexation. The PeerTube server then deals with inter-server ActivityPub operations and propagates information across its social graph by posting activities to actors' inbox endpoints.

https://docs.joinpeertube.org/admin/following-instances#instances-follows

List instances following the server

GET

https://peertube2.cpy.re/api/v1/server/followers

List instances following the server

curl -X GET 'https://peertube2.cpy.re/api/v1/server/followers?count=15'

const response = await fetch('https://peertube2.cpy.re/api/v1/server/followers?count=15', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('https://peertube2.cpy.re/api/v1/server/followers?count=15')
print(response.text)

200

{
  "total": 1,
  "data": [
    {
      "id": 42,
      "follower": {
        "id": 42,
        "url": "https://example.com",
        "avatars": [
          {
            "path": "string",
            "fileUrl": "string",
            "width": 0,
            "height": 0,
            "createdAt": "2024-01-15T09:30:00Z",
            "updatedAt": "2024-01-15T09:30:00Z"
          }
        ],
        "host": "example.com",
        "hostRedundancyAllowed": true,
        "followingCount": 0,
        "followersCount": 0,
        "createdAt": "2024-01-15T09:30:00Z",
        "updatedAt": "2024-01-15T09:30:00Z"
      },
      "following": {
        "id": 42,
        "url": "https://example.com",
        "avatars": [
          {
            "path": "string",
            "fileUrl": "string",
            "width": 0,
            "height": 0,
            "createdAt": "2024-01-15T09:30:00Z",
            "updatedAt": "2024-01-15T09:30:00Z"
          }
        ],
        "host": "example.com",
        "hostRedundancyAllowed": true,
        "followingCount": 0,
        "followersCount": 0,
        "createdAt": "2024-01-15T09:30:00Z",
        "updatedAt": "2024-01-15T09:30:00Z"
      },
      "score": 0,
      "state": "pending",
      "createdAt": "2024-01-15T09:30:00Z",
      "updatedAt": "2024-01-15T09:30:00Z"
    }
  ]
}

Parameters

statestringpendingacceptedquery

actorTypestringPersonApplicationGroupServiceOrganizationquery

startinteger>= 0query

Offset used to paginate results

countinteger[1, 100]15query

Number of items to return

sortstringquery

Sort column

Response

200OKobject

successful operation

Response fields application/json

totalinteger

Example

dataArray<Follow>

Show child attributes

idid>= 1

Example

followerActor

Show child attributes

idid>= 1

Example

urlstring<url>

nameusername

immutable name of the actor, used to find or mention it

Show child attributes

immutable name of the user, used to find or mention its actor

username

Example

chocobozzz

avatarsArray<ActorImage>

Show child attributes

pathstring | nulldeprecated

Deprecated in PeerTube v8.0, use fileUrl instead. Null if the file is stored in object storage: use the non-deprecated field instead.

fileUrlstring

PeerTube >= 7.1

widthinteger

heightinteger

PeerTube >= 7.3

createdAtstring<date-time>

updatedAtstring<date-time>

hoststring<hostname>

server on which the actor is resident

hostRedundancyAllowedboolean | null

whether this actor's host allows redundancy of its videos

followingCountinteger>= 0

number of actors subscribed to by this actor, as seen by this instance

followersCountinteger>= 0

number of followers of this actor, as seen by this instance

createdAtstring<date-time>

updatedAtstring<date-time>

followingActor

Show child attributes

idid>= 1

Example

urlstring<url>

nameusername

immutable name of the actor, used to find or mention it

Show child attributes

immutable name of the user, used to find or mention its actor

username

Example

chocobozzz

avatarsArray<ActorImage>

Show child attributes

pathstring | nulldeprecated

Deprecated in PeerTube v8.0, use fileUrl instead. Null if the file is stored in object storage: use the non-deprecated field instead.

fileUrlstring

PeerTube >= 7.1

widthinteger

heightinteger

PeerTube >= 7.3

createdAtstring<date-time>

updatedAtstring<date-time>

hoststring<hostname>

server on which the actor is resident

hostRedundancyAllowedboolean | null

whether this actor's host allows redundancy of its videos

followingCountinteger>= 0

number of actors subscribed to by this actor, as seen by this instance

followersCountinteger>= 0

number of followers of this actor, as seen by this instance

createdAtstring<date-time>

updatedAtstring<date-time>

scorenumber

score reflecting the reachability of the actor, with steps of 10 and a base score of 1000.

statestringpendingaccepted

createdAtstring<date-time>

updatedAtstring<date-time>

Remove or reject a follower to your server

DELETE

https://peertube2.cpy.re/api/v1/server/followers/{handle}

Remove or reject a follower to your server

curl -X DELETE 'https://peertube2.cpy.re/api/v1/server/followers/user%40example.com' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('https://peertube2.cpy.re/api/v1/server/followers/user%40example.com', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'https://peertube2.cpy.re/api/v1/server/followers/user%40example.com',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

Parameters

handlestring<email>requiredpath

The remote actor handle to remove from your followers

Response

204No Content

successful operation

404Not Found

follower not found

Authorization

OAuth2oauth2

Authenticating via OAuth requires the following steps:

Have an activated account
Generate an access token for that account at /api/v1/users/token.
Make requests with the Authorization: Bearer <token> header
Profit, depending on the role assigned to the account

Note that the access token is valid for 1 day and is given along with a refresh token valid for 2 weeks.

Scopes: admin

Reject a pending follower to your server

POST

https://peertube2.cpy.re/api/v1/server/followers/{handle}/reject

Reject a pending follower to your server

curl -X POST 'https://peertube2.cpy.re/api/v1/server/followers/user%40example.com/reject' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('https://peertube2.cpy.re/api/v1/server/followers/user%40example.com/reject', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.post(
    'https://peertube2.cpy.re/api/v1/server/followers/user%40example.com/reject',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

Parameters

handlestring<email>requiredpath

The remote actor handle to remove from your followers

Response

204No Content

successful operation

404Not Found

follower not found

Authorization

OAuth2oauth2

Authenticating via OAuth requires the following steps:

Have an activated account
Generate an access token for that account at /api/v1/users/token.
Make requests with the Authorization: Bearer <token> header
Profit, depending on the role assigned to the account

Note that the access token is valid for 1 day and is given along with a refresh token valid for 2 weeks.

Scopes: admin

Accept a pending follower to your server

POST

https://peertube2.cpy.re/api/v1/server/followers/{handle}/accept

Accept a pending follower to your server

curl -X POST 'https://peertube2.cpy.re/api/v1/server/followers/user%40example.com/accept' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('https://peertube2.cpy.re/api/v1/server/followers/user%40example.com/accept', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.post(
    'https://peertube2.cpy.re/api/v1/server/followers/user%40example.com/accept',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

Parameters

handlestring<email>requiredpath

The remote actor handle to remove from your followers

Response

204No Content

successful operation

404Not Found

follower not found

Authorization

OAuth2oauth2

Authenticating via OAuth requires the following steps:

Have an activated account
Generate an access token for that account at /api/v1/users/token.
Make requests with the Authorization: Bearer <token> header
Profit, depending on the role assigned to the account

Note that the access token is valid for 1 day and is given along with a refresh token valid for 2 weeks.

Scopes: admin

List instances followed by the server

GET

https://peertube2.cpy.re/api/v1/server/following

List instances followed by the server

curl -X GET 'https://peertube2.cpy.re/api/v1/server/following?count=15'

const response = await fetch('https://peertube2.cpy.re/api/v1/server/following?count=15', {
  method: 'GET',
});

const data = await response.text();

import requests

response = requests.get('https://peertube2.cpy.re/api/v1/server/following?count=15')
print(response.text)

200

{
  "total": 1,
  "data": [
    {
      "id": 42,
      "follower": {
        "id": 42,
        "url": "https://example.com",
        "avatars": [
          {
            "path": "string",
            "fileUrl": "string",
            "width": 0,
            "height": 0,
            "createdAt": "2024-01-15T09:30:00Z",
            "updatedAt": "2024-01-15T09:30:00Z"
          }
        ],
        "host": "example.com",
        "hostRedundancyAllowed": true,
        "followingCount": 0,
        "followersCount": 0,
        "createdAt": "2024-01-15T09:30:00Z",
        "updatedAt": "2024-01-15T09:30:00Z"
      },
      "following": {
        "id": 42,
        "url": "https://example.com",
        "avatars": [
          {
            "path": "string",
            "fileUrl": "string",
            "width": 0,
            "height": 0,
            "createdAt": "2024-01-15T09:30:00Z",
            "updatedAt": "2024-01-15T09:30:00Z"
          }
        ],
        "host": "example.com",
        "hostRedundancyAllowed": true,
        "followingCount": 0,
        "followersCount": 0,
        "createdAt": "2024-01-15T09:30:00Z",
        "updatedAt": "2024-01-15T09:30:00Z"
      },
      "score": 0,
      "state": "pending",
      "createdAt": "2024-01-15T09:30:00Z",
      "updatedAt": "2024-01-15T09:30:00Z"
    }
  ]
}

Parameters

statestringpendingacceptedquery

actorTypestringPersonApplicationGroupServiceOrganizationquery

startinteger>= 0query

Offset used to paginate results

countinteger[1, 100]15query

Number of items to return

sortstringquery

Sort column

Response

200OKobject

successful operation

Response fields application/json

totalinteger

Example

dataArray<Follow>

Show child attributes

idid>= 1

Example

followerActor

Show child attributes

idid>= 1

Example

urlstring<url>

nameusername

immutable name of the actor, used to find or mention it

Show child attributes

immutable name of the user, used to find or mention its actor

username

Example

chocobozzz

avatarsArray<ActorImage>

Show child attributes

pathstring | nulldeprecated

Deprecated in PeerTube v8.0, use fileUrl instead. Null if the file is stored in object storage: use the non-deprecated field instead.

fileUrlstring

PeerTube >= 7.1

widthinteger

heightinteger

PeerTube >= 7.3

createdAtstring<date-time>

updatedAtstring<date-time>

hoststring<hostname>

server on which the actor is resident

hostRedundancyAllowedboolean | null

whether this actor's host allows redundancy of its videos

followingCountinteger>= 0

number of actors subscribed to by this actor, as seen by this instance

followersCountinteger>= 0

number of followers of this actor, as seen by this instance

createdAtstring<date-time>

updatedAtstring<date-time>

followingActor

Show child attributes

idid>= 1

Example

urlstring<url>

nameusername

immutable name of the actor, used to find or mention it

Show child attributes

immutable name of the user, used to find or mention its actor

username

Example

chocobozzz

avatarsArray<ActorImage>

Show child attributes

pathstring | nulldeprecated

Deprecated in PeerTube v8.0, use fileUrl instead. Null if the file is stored in object storage: use the non-deprecated field instead.

fileUrlstring

PeerTube >= 7.1

widthinteger

heightinteger

PeerTube >= 7.3

createdAtstring<date-time>

updatedAtstring<date-time>

hoststring<hostname>

server on which the actor is resident

hostRedundancyAllowedboolean | null

whether this actor's host allows redundancy of its videos

followingCountinteger>= 0

number of actors subscribed to by this actor, as seen by this instance

followersCountinteger>= 0

number of followers of this actor, as seen by this instance

createdAtstring<date-time>

updatedAtstring<date-time>

scorenumber

score reflecting the reachability of the actor, with steps of 10 and a base score of 1000.

statestringpendingaccepted

createdAtstring<date-time>

updatedAtstring<date-time>

Follow a list of actors (PeerTube instance, channel or account)

POST

https://peertube2.cpy.re/api/v1/server/following

Follow a list of actors (PeerTube instance, channel or account)

curl -X POST 'https://peertube2.cpy.re/api/v1/server/following' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "hosts": [
    "example.com"
  ],
  "handles": [
    "string"
  ]
}'

const body = `{
  "hosts": [
    "example.com"
  ],
  "handles": [
    "string"
  ]
}`;

const response = await fetch('https://peertube2.cpy.re/api/v1/server/following', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json',
  },
  body,
});

const data = await response.text();

import requests

body = '''{
  "hosts": [
    "example.com"
  ],
  "handles": [
    "string"
  ]
}'''

response = requests.post(
    'https://peertube2.cpy.re/api/v1/server/following',
    data=body.encode('utf-8'),
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
        'Content-Type': 'application/json',
    },
)
print(response.text)

Request Body

{
  "hosts": [
    "example.com"
  ],
  "handles": [
    "string"
  ]
}

Body

application/json

hostsArray<string>

handlesArray<string>

Response

204No Content

successful operation

500Internal Server Error

cannot follow a non-HTTPS server

Authorization

OAuth2oauth2

Authenticating via OAuth requires the following steps:

Have an activated account
Generate an access token for that account at /api/v1/users/token.
Make requests with the Authorization: Bearer <token> header
Profit, depending on the role assigned to the account

Note that the access token is valid for 1 day and is given along with a refresh token valid for 2 weeks.

Scopes: admin

Unfollow an actor (PeerTube instance, channel or account)

DELETE

https://peertube2.cpy.re/api/v1/server/following/{hostOrHandle}

Unfollow an actor (PeerTube instance, channel or account)

curl -X DELETE 'https://peertube2.cpy.re/api/v1/server/following/string' \
  -H 'Authorization: Bearer YOUR_TOKEN'

const response = await fetch('https://peertube2.cpy.re/api/v1/server/following/string', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
  },
});

const data = await response.text();

import requests

response = requests.delete(
    'https://peertube2.cpy.re/api/v1/server/following/string',
    headers={
        'Authorization': 'Bearer YOUR_TOKEN',
    },
)
print(response.text)

Parameters

hostOrHandlestringrequiredpath

The hostOrHandle to unfollow

Response

204No Content

successful operation

404Not Found

host or handle not found

Authorization

OAuth2oauth2

Authenticating via OAuth requires the following steps:

Have an activated account
Generate an access token for that account at /api/v1/users/token.
Make requests with the Authorization: Bearer <token> header
Profit, depending on the role assigned to the account

Note that the access token is valid for 1 day and is given along with a refresh token valid for 2 weeks.

Scopes: admin

Docs by Sourcey