Social API

The Social API provides endpoints to list, get and create subsocial entities used in the Grill widgetopen in new window. Spaces and posts are the main entities provided by it, which may be a bit unfamiliar to a developer who is trying to include the Grill widget into a website. Apillon changes the naming of these entities into Hub and Channel, and takes care of the whole blockchain and IPFS aspect, the result being a simple configuration which can be used to setup a Grill widget on any website.

Note: You can also create channels and hubs in the Apillon dashboardopen in new window.

Use the Social API to create hubs and channels from your application. For example: you can create a channel (chatroom) for each NFT collection in your marketplace.

In all cURL examples, parameters with a colon as a prefix should be replaced with real values.

Channels

By default, a channel is created inside a hub, therefore a hub can contain multiple channels. The grill widget displays hubs as a list of channels inside it, and a channel is displayed as a chatroom. A channel can be created inside Apillon's default hub or you can create your own hub and create channels within it.

List channels

API to list all channels. Items are paginated and can be filtered and ordered through query parameters as described here .

GET /social/channels

Query parameters

All query parameters from listing request plus:

NameDescriptionRequired
hubUuidParent hub unique identifierfalse

Response fields (channel)

Each item is an instance of channel class, with below properties:

FieldTypeDescription
channelUuidstringChannel unique identifier
hubUuidstringUnique identifier of the channel's parent Hub
channelIdnumberChannel id on Subsocial chain. This id is used in widget.
statusnumberChannel status (1: draft - deploying to chain, 5: active, 100: error)
titlestringChannel name
bodystringChannel body - short description
tagsstringComma separated tags
createTimeDateTimeItem create time
updateTimeDateTimeItem last update time

curl --location --request GET "https://api.apillon.io/social/channels" \
--header "Authorization: Basic :credentials"
curl --location --request GET "https://api.apillon.io/social/channels?search=My" \
--header "Authorization: Basic :credentials"
{
  "id": "d9ee5982-4292-40ee-b94f-b5c234fecb98",
  "status": 200,
  "data": {
    "items": [
      {
        "channelUuid": "6f08bafe-bfd2-4151-bae1-99e515bd6c55",
        "hubUuid": "d6355fd3-640d-4803-a4d9-79d875abcb5a",
        "channelId": 512,
        "status": 1,
        "title": "My ApillonAPI channel",
        "body": "ApillonAPI channel",
        "tags": "web3,fun",
        "createTime": "2024-03-05T13:23:20.000Z",
        "updateTime": "2024-03-05T13:23:20.000Z",
      },
      ...
    ],
    "total": 4,
    "page": 1,
    "limit": 20
  }
}

Get channel

Endpoint to get a single channel. Returns basic channel data.

GET /social/channels/:channelUuid

URL parameters

NameDescriptionRequired
channelUuidChannel unique identifiertrue

Possible errors

CodeDescription
40419001Channel does not exists

Response fields

Response is an instance of channel class, described above.


curl --location --request GET "https://api.apillon.io/social/channels/:channelUuid" \
--header "Authorization: Basic :credentials"
{
  "id": "4a14a0de-6dd5-4863-b031-664aa9b4b13e",
  "status": 200,
  "data": {
    "status": 1,
    "createTime": "2024-03-05T13:23:20.000Z",
    "updateTime": "2024-03-05T13:23:20.000Z",
    "title": "My ApillonAPI channel",
    "body": "ApillonAPI channel",
    "tags": "web3,fun",
    "channelUuid": "6f08bafe-bfd2-4151-bae1-99e515bd6c55",
    "channelId": 512
  }
}

Create channel

API that creates channel and transmits it to blockchain. Transaction can take a while and until confirmed, channel has status 1.

POST /social/channels

Body fields

NameTypeDescriptionRequired
titlestringChannel nametrue
bodystringChannel content/descriptiontrue
tagsstringComma separated tagsfalse
hubUuidstringHub unique identifier - if not specified the channel is created inside a default hubfalse

Possible errors

CodeDescription
40419001Specified hub does not exist
42219002Body is missing required properties
50019004Parent hub is in invalid state. It is probably not yet transmitted and confirmed on the chain (status = 1)
50019003Internal error - Apillon was unable to create channel.

Response

Response is an instance of channel class, described above.


curl --location --request POST "https://api.apillon.io/social/channels" \
--header "Authorization: Basic :credentials" \
--header "Content-Type: application/json" \
--data-raw "{
    \"title\": \"Apillon API channel\",
    \"body\": \"Lets talk about apillon API\",
    \"tags\": \"Apillon,API,WEB3\"
}"
{
  "id": "68c32a2c-f2b0-4580-916b-2c1b12926228",
  "status": 201,
  "data": {
    "status": 1,
    "createTime": "2024-03-06T20:28:12.309Z",
    "updateTime": null,
    "title": "Apillon API channel",
    "body": "Lets talk about apillon API",
    "tags": "Apillon,API,WEB3",
    "channelUuid": "c1d709b8-16fb-493e-a317-16d8b8ce623d",
    "hubUuid": "d6355fd3-640d-4803-a4d9-79d875abcb5a",
    "channelId": null
  }
}

Hubs

List hubs

API to list all hubs in project. Items are paginated and can be filtered and ordered through query parameters as described here .

GET /social/hubs

Response fields (hub)

Each item is an instance of hub class, with below properties:

FieldTypeDescription
hubUuidstringHub unique identifier
hubIdnumberHub id on Subsocial chain. This id is used in widget or in grillapp.net. Example: https://grillapp.net/12927.
statusnumberHub status (1: draft - deploying to chain, 5: active, 100: error)
namestringHub name
aboutstringHub about - short description
tagsstringComma separated tags
numOfChannelsnumberNumber of channels in hub
createTimeDateTimeItem create time
updateTimeDateTimeItem last update time

curl --location --request GET "https://api.apillon.io/social/hubs" \
--header "Authorization: Basic :credentials"
curl --location --request GET "https://api.apillon.io/storage/buckets?search=My hub" \
--header "Authorization: Basic :credentials"
{
  "id": "88b3140f-035e-446d-bda7-1f95e7343619",
  "status": 200,
  "data": {
    "items": [
      {
        "hubUuid": "7b59dc14-5ea1-48df-b4c9-a8395690d225",
        "hubId": "55545",
        "status": 5,
        "createTime": "2024-03-05T12:18:20.000Z",
        "updateTime": "2024-03-05T13:21:25.000Z",
        "name": "Apillon API hub",
        "about": "Apillon API hub",
        "tags": "web3,fun",
        "numOfChannels": 4
      }
      ...
    ],
    "total": 3,
    "page": 1,
    "limit": 20
  }
}

Get hub

Endpoint to get hub. Endpoint returns basic hub data.

GET /social/hubs/:hubUuid

URL parameters

NameDescriptionRequired
hubUuidHub UUID, visible in developer consoletrue

Possible errors

CodeDescription
40419001Hub does not exists

Response fields

Response is an instance of hub class, described above. Only difference is field numOfChannels, which is not returned by this endpoint.


curl --location --request GET "https://api.apillon.io/social/hubs/:hubUuid" \
--header "Authorization: Basic :credentials"
{
  "id": "e4ec496a-121a-4033-9451-5b53ae3d0307",
  "status": 200,
  "data": {
    "status": 5,
    "createTime": "2024-03-05T12:18:20.000Z",
    "updateTime": "2024-03-05T13:21:25.000Z",
    "name": "Apillon API hub",
    "about": "Apillon API hub",
    "tags": "web3,fun",
    "hubUuid": "7b59dc14-5ea1-48df-b4c9-a8395690d225",
    "hubId": "55545"
  }
}

Create hub

Endpoint to create a hub and transmit it to blockchain. Transaction can take a while and until confirmed, the hub has status 1 (Draft).

POST /social/hubs

Body fields

NameTypeDescriptionRequired
namestringHub name.true
aboutstringHub descriptionfalse
tagsstringComma separated tagsfalse

Possible errors

CodeDescription
42219001Body is missing required properties
50019002Internal error - Apillon was unable to create hub.

Response

Response is an instance of hub class, described above.


curl --location --request POST "https://api.apillon.io/social/hubs" \
--header "Authorization: Basic :credentials" \
--header "Content-Type: application/json" \
--data-raw "{
    \"name\": \"Apillon API hub\",
    \"about\": \"Apillon API hub\",
    \"tags\": \"Apillon,API,WEB3\"
}"
{
  "id": "6570cd41-4401-4ba4-92e8-060617f18f65",
  "status": 201,
  "data": {
    "status": 1,
    "createTime": "2024-03-06T20:28:12.309Z",
    "updateTime": null,
    "name": "Apillon API hub",
    "about": "Apillon API hub",
    "tags": "Apillon,API,WEB3",
    "hubUuid": "65527f5b-054d-453a-a9a9-b29cd00b39bb",
    "hubId": null
  }
}