Getting Started

Welcome to the official Imperial Secrets API for Imperial's anonymous confessions page. The goal of this API is to provide you with secrets that have been posted so you can do cool stuff. For example, make a discord bot to post all secrets there.

To get API access, just contact the page, and we will set you up an account with a username and password.

How to use

Simply hit the https://imperial-secrets-bot-v2.herokuapp.com/api endpoint with the correct auth header to get the most recent N submissions that have been posted to facebook.

The api uses HTTP Basic Authorization. This means you put your username and password in the header of the request as base 64. We recommend using Postman to try out some requests, and use the Basic Auth option in the Authorization tab:

img

If you are too cool to use postman, then just make sure you have this header:

Authorization: Basic <username:password (but encoded as base 64)>

You can also add a limit query parameter to the request. The default is 10, the max is 200.

note

The server that hosts the API can go to sleep (since we are cheapskates that use free tier). Therefore, it sometimes might take around 30 seconds for the server to respond, so bear this in mind. Once the server is awake, it will respond to requests at normal speed until it goes to sleep again.

warning

There is a quota to the number of requests you can make to the server a day. Please design your bots efficiently so they don't get rate limited.

The shape of the data

The json data returned will be an array of objects that look like this:

{
"submissionId": "<The id of the submission>",
"mainSecret": "<The raw, unprettified secret>",
"course": "<The course of the OP>",
"year": "<The year the OP is in>",
"prettifiedSecret": "<The nicely formatted secret that is actually posted to facebook",
"timeSubmitted": "<The time the secret was submitted>",
"responseToSecret": "<If this secret is in response to another secret, this is the number of that secret>",
"timeReviewed": "<The time this secret was reviewed by one of our admins>",
"imperialSecretNumber": "<The number of this secret>",
"isPostedOnFB": "<Is the secret posted on facebook yet (it should always be true)>",
"timeScheduledToPostSecs": "The timestamp this secret was scheduled to post on facebook",
"mood": "<The mood selected by the OP in the secret>",
"image": "<The base 64 encoded image if there is one on the secret>",
"isVideo": "<We don't support video links in the api at the moment, but this field tells you if the submission is a video>",
"timeAssignedToReviewer": "<The time this submission was assigned to an admin to review",
"poll": "<An array of poll options that the OP submitted>",
"hasSentEmailNotif": "<If the OP selected to receive email notifications, whether the email has sent or not yet>",
"fbPostId": "<The id of the post on facebook. Can be viewed by going to facebook.com/the_fb_post_id_here>",
"isAiResponseEnabled": "<Whether the OP allowed for chatbot response or not>"
}

Sample code

Here is some sample python to make the request:

import requests
import json
url = 'https://imperial-secrets-bot-v2.herokuapp.com/api'
params = {'limit': 69}
auth = ('<USERNAME>', '<PASSWORD>')
res = requests.get(url, params=params, auth=auth)
content = json.loads(res.content)