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.

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, ...)
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",
            "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",
            "created_at": "2021-05-12 02:08:03"
        }
    ],
    "has_more_page": false
}

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}/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, ...)
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",
            "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",
            "created_at": "2021-05-12 02:08:03"
        }
    ],
    "has_more_page": false
}

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}/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, ...)
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",
            "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",
            "created_at": "2021-05-12 02:08:03"
        }
    ],
    "has_more_page": false
}

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"
}

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": {
        "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"
    }
}

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, tt721 vibe)
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
}