Open API

OurSong Open API is currently in beta, if you want to use OurSong Open API, please contact dev@oursong.com with the title "Apply for OurSong Open API", and briefly describe your purpose of use, we will contact you as soon as possible, thank you!

API List

OAuth

Before you start, please make sure you have API key and API secret on hand.

Get the authenticate code from a OurSong user.

End Point
GET
https://www.oursong.com/oauth/authorize
Request
Header
Accept
text/html
Parameter
client_id (reqired)
YOUR_API_KEY
redirect_uri (reqired)
YOUR_CALLBACK_URI (you provided when applying the API key)
response_type (reqired)
code (don't change this)
state (optinal)
you_complete_me (any other will do, will redirect to your callback uri too)
Response

If the user doesn't login OurSong yet, the user will be redirected to OurSong login page.

When the user login OurSong, the user will be asked for authorizing the code to your APP.

If the user authorize the code to your APP, then OurSong will redirect the authorized code to your APP!

Now you can use the authenticate code to get the access token.

End Point
POST
https://www.oursong.com/oauth/token
Request
Header
Accept
application/json
Parameter
grant_type (reqired)
authorization_code (don't change this)
client_id (reqired)
YOUR_API_KEY
client_secret (reqired)
YOUR_API_SECRET
redirect_uri (reqired)
YOUR_CALLBACK_URI (you provided when applying the API key)
code (reqired)
def502......6bbde0 (redirected from step1)
Response
Body
{
    "token_type": "Bearer",
    "expires_in": 31535999,
    "access_token": "eyJ0eX......AiOiJK",
    "refresh_token": "def502......002d9a"
}

Please protect this access token for the user, and you can keep this access token for further use.

Login with Connected Wallet

If the user have connected the wallet to the user's OurSong account, then can use this api to login to the user's OurSong account.

End Point
POST
https://www.oursong.com/api/open-api/wallet-login
Request
Header
Accept
application/json
Parameter
api_key (reqired)
YOUR_API_KEY
api_secret (reqired)
YOUR_API_SECRET
wallet_address (reqired)
0x17......fbe (the connected wallet address)
sign_data (reqired)
0x... ("hello" to hex)
sign_encoded (reqired)
0x... (sign "hello" hex using personal sign)
Response
Body
  {
      "status": "success",
      "message": "Success!",
      "access_token": "..."
  }
  

Access Token Free API List

Get the token spec list OurSong spports.

End Point
GET
https://www.oursong.com/api/open-api/token-spec-list
Request
Header
Accept
application/json
Parameter
api_key (reqired)
YOUR_API_KEY
Response
Body
{
    "status": "success",
    "message": "Success!",
    "list": [
        {
            "token_spec": "erc721",
            "end_point": "https://www.oursong.com/api/open-api/token-spec/erc721/vibe-list",
            "param": [
                "page"
            ],
            "example": "https://www.oursong.com/api/open-api/token-spec/erc721/vibe-list?page=1"
        },
        ...
        ...
        ...
        {
            "token_spec": "tt1155",
            "end_point": "https://www.oursong.com/api/open-api/token-spec/tt1155/vibe-list",
            "param": [
                "page"
            ],
            "example": "https://www.oursong.com/api/open-api/token-spec/tt1155/vibe-list?page=1"
        }
    ]
}

Get the vibe list of the token spec.

End Point
GET
https://www.oursong.com/api/open-api/token-spec/{token_spec}/vibe-list

You can get token spec list from Token Spec List API, and put the token spec you want to use in this end point.

Request
Header
Accept
application/json
Parameter
api_key (reqired)
YOUR_API_KEY
page (optional)
1 (or 2, 3, ...)
per_page (optional)
20 (default is 20, max is 100)
Response
Body
{
    "status": "success",
    "message": "Success!",
    "list": [
        {
            "id": "nxwyqqow",
            "title": "Coldplay - Yellow",
            "description": "Coldplay - Yellow",
            "token_spec": "tt721",
            "contract_address": "0x4888cd354a13606992793468a628f9e6c8efd847",
            "token_id_start": "1",
            "token_id_end": "10",
            "base_uri": "https://www.oursong.com/project/nxwyqqow/erc721token-meta/",
            "contract_uri": "https://www.oursong.com/project/nxwyqqow/erc721contract-meta",
            "example_base_uri": "https://www.oursong.com/project/nxwyqqow/erc721token-meta/1",
            "cover_image": "cover_image_url",
            "image": "image_url",
            "animation_url": "animation_url",
            "content_type": "video",
            "created_at": "2021-05-17 08:26:04"
        },
        ...
        ...
        ...
        {
            "id": "xdwbppyw",
            "title": "Don’t Stop Me Now",
            "description": "Don’t Stop Me Now",
            "token_spec": "tt721",
            "contract_address": "0xfa8b94e9178de5b1c53565200c5d9e2f925bce8d",
            "token_id_start": "1",
            "token_id_end": "5",
            "base_uri": "https://www.oursong.com/project/xdwbppyw/erc721token-meta/",
            "contract_uri": "https://www.oursong.com/project/xdwbppyw/erc721contract-meta",
            "example_base_uri": "https://www.oursong.com/project/xdwbppyw/erc721token-meta/1",
            "cover_image": "cover_image_url",
            "image": "image_url",
            "animation_url": "animation_url",
            "content_type": "video",
            "created_at": "2021-05-12 02:08:03"
        }
    ],
    "current_page": 1,
    "per_page": 20,
    "total": 27,
    "has_more_page": true
}

Get the user collected vibe list. The default will fetch public vibes, can fetch hidden vibes by using access token.

End Point
GET
https://www.oursong.com/api/open-api/user/{user_id or uuid}/collected-vibe-list
Request
Header
Accept
application/json
Authorization (optional)
Bearer ACCESS_TOKEN_OF_THE_USER
Parameter
api_key (reqired)
YOUR_API_KEY
page (optional)
1 (or 2, 3, ...)
per_page (optional)
20 (default is 20, max is 100)
token_spec (optional)
erc721,erc1155,polygon721,polygon1155 (you can query multiple spec using comma seperate form)
content_type (optional)
video,audio,photo,3dmodel (you can query multiple spec using comma seperate form)
Response
Body
{
    "status": "success",
    "message": "Success!",
    "list": [
        {
            "id": "nxwyqqow",
            "title": "Coldplay - Yellow",
            "description": "Coldplay - Yellow",
            "token_spec": "tt721",
            "contract_address": "0x4888cd354a13606992793468a628f9e6c8efd847",
            "token_id_start": "1",
            "token_id_end": "10",
            "base_uri": "https://www.oursong.com/project/nxwyqqow/erc721token-meta/",
            "contract_uri": "https://www.oursong.com/project/nxwyqqow/erc721contract-meta",
            "example_base_uri": "https://www.oursong.com/project/nxwyqqow/erc721token-meta/1",
            "cover_image": "cover_image_url",
            "image": "image_url",
            "animation_url": "animation_url",
            "content_type": "video",
            "created_at": "2021-05-17 08:26:04"
        },
        ...
        ...
        ...
        {
            "id": "xdwbppyw",
            "title": "Don’t Stop Me Now",
            "description": "Don’t Stop Me Now",
            "token_spec": "tt721",
            "contract_address": "0xfa8b94e9178de5b1c53565200c5d9e2f925bce8d",
            "token_id_start": "1",
            "token_id_end": "5",
            "base_uri": "https://www.oursong.com/project/xdwbppyw/erc721token-meta/",
            "contract_uri": "https://www.oursong.com/project/xdwbppyw/erc721contract-meta",
            "example_base_uri": "https://www.oursong.com/project/xdwbppyw/erc721token-meta/1",
            "cover_image": "cover_image_url",
            "image": "image_url",
            "animation_url": "animation_url",
            "content_type": "video",
            "created_at": "2021-05-12 02:08:03"
        }
    ],
    "current_page": 1,
    "per_page": 20,
    "total": 27,
    "has_more_page": true
}

Get the user created vibe list. The default will fetch public vibes, can fetch hidden vibes by using access token.

End Point
GET
https://www.oursong.com/api/open-api/user/{user_id or uuid}/created-vibe-list
Request
Header
Accept
application/json
Authorization (optional)
Bearer ACCESS_TOKEN_OF_THE_USER
Parameter
api_key (reqired)
YOUR_API_KEY
page (optional)
1 (or 2, 3, ...)
per_page (optional)
20 (default is 20, max is 100)
token_spec (optional)
erc721,erc1155,polygon721,polygon1155 (you can query multiple spec using comma seperate form)
content_type (optional)
video,audio,photo,3dmodel (you can query multiple spec using comma seperate form)
Response
Body
{
    "status": "success",
    "message": "Success!",
    "list": [
        {
            "id": "nxwyqqow",
            "title": "Coldplay - Yellow",
            "description": "Coldplay - Yellow",
            "token_spec": "tt721",
            "contract_address": "0x4888cd354a13606992793468a628f9e6c8efd847",
            "token_id_start": "1",
            "token_id_end": "10",
            "base_uri": "https://www.oursong.com/project/nxwyqqow/erc721token-meta/",
            "contract_uri": "https://www.oursong.com/project/nxwyqqow/erc721contract-meta",
            "example_base_uri": "https://www.oursong.com/project/nxwyqqow/erc721token-meta/1",
            "cover_image": "cover_image_url",
            "image": "image_url",
            "animation_url": "animation_url",
            "content_type": "video",
            "created_at": "2021-05-17 08:26:04"
        },
        ...
        ...
        ...
        {
            "id": "xdwbppyw",
            "title": "Don’t Stop Me Now",
            "description": "Don’t Stop Me Now",
            "token_spec": "tt721",
            "contract_address": "0xfa8b94e9178de5b1c53565200c5d9e2f925bce8d",
            "token_id_start": "1",
            "token_id_end": "5",
            "base_uri": "https://www.oursong.com/project/xdwbppyw/erc721token-meta/",
            "contract_uri": "https://www.oursong.com/project/xdwbppyw/erc721contract-meta",
            "example_base_uri": "https://www.oursong.com/project/xdwbppyw/erc721token-meta/1",
            "cover_image": "cover_image_url",
            "image": "image_url",
            "animation_url": "animation_url",
            "content_type": "video",
            "created_at": "2021-05-12 02:08:03"
        }
    ],
    "current_page": 1,
    "per_page": 20,
    "total": 27,
    "has_more_page": true
}

Get the user owned vibe token id list. One user may have multiple token ids in one vibe, use this API to fetch the token id list.

End Point
GET
https://www.oursong.com/api/open-api/user/{user_id or uuid}/vibe/{vibe_id}/owned-token-id-list
Request
Header
Accept
application/json
Authorization (optional)
Bearer ACCESS_TOKEN_OF_THE_USER
Parameter
api_key (reqired)
YOUR_API_KEY
page (optional)
1 (or 2, 3, ...)
per_page (optional)
20 (default is 20, max is 100)
Response
Body
{
    "status": "success",
    "message": "Success!",
    "song_project": {
        "id": "mzwkaxwy",
        "title": "Under Pressure",
        "description": "Under Pressure",
        "token_spec": "erc721",
        "contract_address": "0xf2e2d4401ea2a40db585f35cb6eab87a9e2d1579"
    },
    "owned_token_id_list": [
        2,
        3,
        5,
        6,
        7,
        8,
        9,
        10,
        11,
        12,
        13,
        14,
        15,
        16,
        17,
        18,
        19,
        20,
        21,
        22
    ],
    "current_page": 1,
    "per_page": 20,
    "total": 27,
    "has_more_page": true
}

Get the vibe profile

End Point
GET
https://www.oursong.com/api/open-api/vibe/{vibe_id}/profile
Request
Header
Accept
application/json
Authorization (optional)
Bearer ACCESS_TOKEN_OF_THE_USER
Parameter
api_key (reqired)
YOUR_API_KEY
Response
Body
{
    "id": "npwjlbwq",
    "name": "Video Killed The Radio Star",
    "description": "Video Killed The Radio Star",
    "cover_image": "https://oursong-stage.s3.amazonaws.com/projects/sst-design/cf4a51e5-4d80-4844-9b55-b31fdea8d19d.jpg",
    "image": "https://oursong-stage.s3.amazonaws.com/projects/sst-design/cf4a51e5-4d80-4844-9b55-b31fdea8d19d.jpg",
    "animation_url": "https://oursong-stage.s3.ap-southeast-1.amazonaws.com/video/6f60d7bb-00e6-41ea-961a-f7d731c7f7e0_preview.mp4?X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAJFSWCB27XGG4CKEQ%2F20211013%2Fap-southeast-1%2Fs3%2Faws4_request&X-Amz-Date=20211013T102345Z&X-Amz-SignedHeaders=host&X-Amz-Expires=600&X-Amz-Signature=720ad4005445f648890f22b81fe3dd239685852176b90ccdbc5c0cdc077ab757",
    "external_url": "http://major-tom-web-app.test/project/npwjlbwq",
    "content_type": "video",
    "issuer": {
      "uuid": "xxx...xxx",
      "id": "queen",
      "name": "Queen",
      "username": "queen",
      "avatar": "https://oursong-stage.s3.amazonaws.com/avatar/...jpg",
      "avatar_m": "https://oursong-stage.s3.amazonaws.com/avatar/....jpg",
      "avatar_b": "https://oursong-stage.s3.amazonaws.com/avatar/....jpg"
    }
}

Get vibe holder list.

End Point
GET
https://www.oursong.com/api/open-api/vibe/{vibe_id}/holder-list
Request
Header
Accept
application/json
Authorization (optional)
Bearer ACCESS_TOKEN_OF_THE_USER
Parameter
api_key (reqired)
YOUR_API_KEY
page (optional)
1 (or 2, 3, ...)
per_page (optional)
20 (default is 20, max is 100)
Response
Body
{
    "status": "success",
    "message": "Success!",
    "song_project": {
        "id": "mzwkaxwy",
        "title": "Under Pressure",
        "description": "Under Pressure",
        "token_spec": "erc721",
        "contract_address": "0xf2e2d4401ea2a40db585f35cb6eab87a9e2d1579"
    },
    "holder_list": [
        {
            "uuid": "xxx...xxx",
            "id": "king",
            "name": "King",
            "username": "king",
            "avatar": "https://oursong-stage.s3.amazonaws.com/avatar/....jpg",
            "avatar_m": "https://oursong-stage.s3.amazonaws.com/avatar/....jpg",
            "avatar_b": "https://oursong-stage.s3.amazonaws.com/avatar/....jpg",
            "owned_amount": 98
        },
        ...
        {
            "uuid": "xxx...xxx",
            "id": "queen",
            "name": "Queen",
            "username": "queen",
            "avatar": "https://oursong-stage.s3.amazonaws.com/avatar/....jpg",
            "avatar_m": "https://oursong-stage.s3.amazonaws.com/avatar/....jpg",
            "avatar_b": "https://oursong-stage.s3.amazonaws.com/avatar/...jpg",
            "owned_amount": 2
        }
    ],
    "current_page": 1,
    "per_page": 20,
    "total": 27,
    "has_more_page": true
}

Access Token Required API List

Get the authenticated user's basic profile.

End Point
GET
https://www.oursong.com/api/open-api/auth-user
Request
Header
Accept
application/json
Authorization (required)
Bearer ACCESS_TOKEN_OF_THE_USER
Parameter
api_key (reqired)
YOUR_API_KEY
Response
Body
{
    "status": "success",
    "message": "Success!",
    "user": {
        "uuid": "xxx...xxx",
        "id": "dev",
        "name": "Dev",
        "username": "dev",
        "email": "dev@oursong.com",
        "avatar": "https://cdn.com/avatar/1c2eb5c2-688d-4c94-924a-7d72b8945fab_480.jpg",
        "avatar_m": "https://cdn.com/avatar/1c2eb5c2-688d-4c94-924a-7d72b8945fab_480.jpg",
        "avatar_b": "https://cdn.com/avatar/1c2eb5c2-688d-4c94-924a-7d72b8945fab_960.jpg",
        "wallet_address": "0x......"
    }
}

You can use this API to check whether the authenticated user own this vibe or not. If the owned_amount bigger than 0, means the user owned this vibe.

End Point
GET
https://www.oursong.com/api/open-api/auth-user/own-this-vibe
Request
Header
Accept
application/json
Authorization (required)
Bearer ACCESS_TOKEN_OF_THE_USER
Parameter
api_key (reqired)
YOUR_API_KEY
vibe_id (reqired)
xdrbpvjr (the vibe id, you can get the id from vibe list API)
token_id (optional)
1 (or 2, 3, ..., you may use this to check erc721, bep721, polygon721, tt721 vibe)
page (optional)
1 (or 2, 3, ...)
per_page (optional)
20 (default is 20, max is 100)
Response
Body
{
    "status": "success",
    "message": "Success!",
    "song_project": {
        "id": "xdrbpvjr",
        "title": "Don't Stop Me Now",
        "description": "Don't Stop Me Now",
        "token_spec": "bep1155",
        "contract_address": "0x74247aE0D95E5be00ED105aFe03Ad0a98f3aEd8F"
    },
    "owned_amount": 1155,
    "owned_token_id_list": [
      2,
      3,
      5,
      6,
      7,
      8,
      9,
      10,
      11,
      12,
      13,
      14,
      15,
      16,
      17,
      18,
      19,
      20,
      21,
      22
    ],
    "current_page": 1,
    "per_page": 20,
    "total": 27,
    "has_more_page": true
}

In OurSong auth user api will provide the user's connected wallet address, if you want to implement the wallet connect feature in your client App, please sync the connected wallet to OurSong using this API as well.

End Point
POST
https://www.oursong.com/api/open-api/wallet-connect
Request
Header
Accept
application/json
Authorization (required)
Bearer ACCESS_TOKEN_OF_THE_USER
Parameter
api_key (reqired)
YOUR_API_KEY
wallet_address (reqired)
0x17......fbe (the connected wallet address)
sign_data (reqired)
0x... ("hello" to hex)
sign_encoded (reqired)
0x... (sign "hello" hex using personal sign)
Response
Body
  {
      "status": "success",
      "message": "Success!",
      "wallet_address": "0x......"
  }
  

In OurSong auth user api will provide the user's connected wallet address, if you really want to remove the connected wallet for the user you can use this API, please use it in caution!

End Point
POST
https://www.oursong.com/api/open-api/wallet-disconnect
Request
Header
Accept
application/json
Authorization (required)
Bearer ACCESS_TOKEN_OF_THE_USER
Parameter
api_key (reqired)
YOUR_API_KEY
wallet_address (reqired)
0x17......fbe (the connected wallet address)
sign_data (reqired)
0x... ("hello" to hex)
sign_encoded (reqired)
0x... (sign "hello" hex using personal sign)
Response
Body
  {
      "status": "success",
      "message": "Success!",
      "action_type": "disconnect"
  }