STOMT API v2.11.376
This is the official stomt documentation. Use it to make the world a little bit better.
Request/Response format ¶
Read this first!
To keep the API endpoint flexible, maintainable and extendable, we defined a standard set of custom HTTP headers and a fix output format. In this section you’ll learn how requests are build and how responses will always look like.
Must Read (3 min)
1. APP ID
This header has to be sent with each request you make.
appid: (string) // specific id for your app, website or what you build
How to obtain an appid
-
Register on www.stomt.com
-
Go to Manage > Apps and create an application.
2. Requests that require authentication
You need to send an access-token. You’ll receive one after login, methods marked with [LOGIN REQUIRED] have to be called with a valid token of an user account. Endpoints marked with [LOGIN or ANONYM] can also be accessed with an anonym accounts token, read more about anonym accounts in Authentication.
accesstoken: (string) // token which represents your current session
-
Don’t forget to use HTTPS (Port 443)
-
Set Accept header to “application/json”
-
We recommend Postman REST-Client to test against the API
3. Standard Response Format
-
We will always return content-type
application/json
-
We will always return a response body in the following format:
{
// Always | Some meta information
"meta": {},
// Always | Contains the actual response
"data": (object or array), // The requested entity or an array of entities
// Optional | Only if error occurs
"error": (string) // Human readable error message
}
4. Pagination
Use ?offset=(integer)
and ?limit=(integer)
parameters.
5. Test Environment / stomt Sandbox
Please use our testservers during for development purposes:
-
Test REST API: https://test.rest.stomt.com
-
Test Webplatform: https://test.stomt.com (Platform)
6. Feedback
Please leave your feedback in form of wishes on our stomt-API profile
Authentication ¶
We have three different Authentication flows.
Normal Credential flow
-
Register an user via POST req. to /authentication/
-
Get an access token via POST req. to /authentication/session
Facebook Connect flow
-
Retrieve a Login URL by GET /authentication/facebook/url
-
Redirect the user to the URL you obtained in (1)
-
POST retrieved code and state and login_method:facebook to /authentication/session
Reddit Connect flow
-
Get an Auth-URL per GET /authentication/reddit/authorizationurl
-
Redirect the user to the URL you obtained in (1)
-
POST retrieved code and state and login_method:reddit to /authentication/session
Twitter Connect flow
-
Retrieve a Login URL by GET /authentication/twitter/url
-
Redirect the user to the URL you obtained in (1)
-
POST retrieved oauth_token and oauth_verifier and login_method:twitter to /authentication/session
Anonym Account
You are able to perform a limited amount of actions before registration and transform them in a real afterwards.
- Get an access token by performing any POST request which is flagged with [ANONYM]
- Use this token for all further requests
- To create a real account which contains all earlier actions of the anonym account, perform one of the other flows with the token you have
Login ¶
LoginPOST/authentication/session
Normal authentication with credentials or Facebook-Connect. For FB-Connect you need to sign-in client-side to receive an accesstoken from Facebook.
Example URI
Headers
Content-Type: application/json
Body
{
// For Normal Login
"login_method": "normal",
"emailusername": (string),
"password": (string)
// For Facebook Login
"login_method": "facebook",
"code": (string, optional),
"state": (string, optional, required with code),
"accesstoken": (string, optional)
// For reddit Login
"login_method": "reddit",
"code": (string),
"state": (string)
// For twitter Login
"login_method": "twitter",
"oauth_token": (string),
"oauth_verifier": (string)
// optional for all
"merge": (boolean) // transfer anonym action to signed in account
}
200
Headers
Content-Type: application/json
Body
{
"accesstoken": (string),
"refreshtoken": (string),
"user": (userobject),
"newUser": (boolean) // only true if it is the first login using facebook connect
}
404
Email/Username does not exist
(full response body, because data
is empty)
Headers
Content-Type: application/json
Body
{
"data": [],
"error": "Account not found.",
"meta": []
}
403
Wrong Password
(full response body, because data
is empty)
Headers
Content-Type: application/json
Body
{
"data": [],
"error": "Wrong password.",
"meta": []
}
Stomts ¶
A single stomt object. The stomt resource is the central resource in the stomt API. It represents one paste - a single stomt.
Creates a Stomt ¶
Creates a StomtPOST/stomts
[LOGIN or ANONYM]
This is how the process works:
-
The user selects between “I wish” (positive=false) and “I like”(positive=true)
-
The user searches for a target to get the target_id
Example URI
Headers
Content-Type: application/json
Body
{
"text": (string), // (required, max 1000 characters)
"details": (string), // (optional)
"target_id": (string), // if not specified page of the appid will be used
"positive": (boolean), // (default: false => wish)
"lang": (string), // en, de, ...
"url": (string),
"anonym": (boolean),
"img_name": (string),
"file_uid": (string),
"lonlat": (string), // (float), (float)
"files": [ // zero, one or many files:
{
"file_uid": (string) // File-uid of an already uploaded file
},
{
"data": (string), // Base64 encoded file
"filename": (string) // Custom name e.g. user_actions.log (optional)
}
],
"extradata": {
"labels": (array), // label names that will be attached to the stomt
(json) // any json data you want to attach
},
}
200
Headers
Content-Type: application/json
Body
{
"id" : (string), // slug
"num": (integer), // a numeric id you can refer to / auto-incrementing and stars with 1 for each profile
"positive": (boolean),
"text": (string),
"details": (string),
"textHtml": (string), // custom text parsed as html
"textBeginning": (string), // the text of the first stomt bubble
"textFull": (string), // plain text representation of the stomt
"lang": (string), // en, de, ...
"type": (string), // unset, spam, bug, improvement, feature
"state": (string), // unset, new, seen, indiscussion, inprogress, rejected, implemented, released
"severity": (string), // unset, weak, normal, heavy
"complexity": (string), // unset, low, medium, high
"created_at": (ISO 8601),
"anonym": (boolean),
"images": {
"stomt": { // resized attached image
"url": (string) // image url
},
"stomt_full": { // original attached image
"url": (string) // image url
},
"rendered_stomt": { // stomt rendered as image
"url": (string) // image url
}
},
"files": [{
"file_uid": (string), // unique file id
"filename": (string), // custom file name
"url": (string) // file url
}],
"creator" : {
// Full target object (see Targets)
},
"target" : {
// Full target object (see Targets)
},
"amountAgreements": (integer),
"amountPositive": (integer),
"amountNegative": (integer),
"amountComments": (integer),
"shortlink": (string), // A shortlink which 301 to normal stomt-link
"agreed": { // Only exists if agreed
"positive": (boolean)
}
}
Read a Stomt ¶
Read a StomtGET/stomts/
Example URI
- stomt_id (required, string, `i_like_stomt_so_much`)
string
(required)slug of a stomt
200
Headers
Content-Type: application/json
Body
{
"id" : (string), // slug
"num": (integer), // a numeric id you can refer to / auto-incrementing and stars with 1 for each profile
"positive": (boolean),
"text": (string),
"details": (string),
"textHtml": (string), // custom text parsed as html
"textBeginning": (string), // the text of the first stomt bubble
"textFull": (string), // plain text representation of the stomt
"lang": (string), // en, de, ...
"type": (string), // unset, spam, bug, improvement, feature
"state": (string), // unset, new, seen, indiscussion, inprogress, rejected, implemented, released
"severity": (string), // unset, weak, normal, heavy
"complexity": (string), // unset, low, medium, high
"created_at": (ISO 8601),
"anonym": (boolean),
"images": {
"stomt": { // resized attached image
"url": (string) // image url
},
"stomt_full": { // original attached image
"url": (string) // image url
},
"rendered_stomt": { // stomt rendered as image
"url": (string) // image url
}
},
"files": [{
"file_uid": (string), // unique file id
"filename": (string), // custom file name
"url": (string) // file url
}],
"creator" : {
// Full target object (see Targets)
},
"target" : {
// Full target object (see Targets)
},
"amountAgreements": (integer),
"amountPositive": (integer),
"amountNegative": (integer),
"amountComments": (integer),
"shortlink": (string), // A shortlink which 301 to normal stomt-link
"agreed": { // Only exists if agreed
"positive": (boolean)
}
}
Delete a Stomt ¶
Delete a StomtDELETE/stomts/
[LOGIN or ANONYM]
Example URI
- stomt_id (required, string, `i_like_stomt_so_much`)
string
(required)slug of a stomt
200
Headers
Content-Type: application/json
Body
{
"success" : (boolean)
}
Read Stomt Comments ¶
Read Stomt CommentsGET/stomts/{stomt_id}/comments
Example URI
- stomt_id
string
(required) Example: because-they-have-hashtagsid of a stomt
200
Headers
Content-Type: application/json
Body
{
"id" : (string),
"text": (string),
"state": (string),
"created_at": (ISO 8601),
"anonym": (boolean),
"reaction": (boolean),
"creator" : {
// Full target object (see Targets)
},
"byStomtCreator": (boolean),
"byTargetOwner": (boolean),
"amountSubcomments": (integer),
"amountVotes": (integer),
"amountPositive": (integer),
"amountNegative": (integer),
// Only if subcomments exist
"subs": [
// Array of comments
],
// Only if it is not a subcomment an user voted
"voted": {
"positive": (boolean)
}
}
Targets ¶
Targets are the most important and complex resources. stomt is built to feedback anything, even friends and general things (e.g. I wish life had a pause button). Therefore nearly anything is saved as a Target and depending on its type additional type specific data.
Create a Target ¶
Create a TargetPOST/targets
[LOGIN REQUIRED]
Example URI
Headers
Content-Type: application/json
Body
{
"displayname": (string), // required
"category_id": (string), // required, existing category id
"username": (string), // optional, unique slug
"image": (string), // optional, name of an uploaded image
"parent_id": (string), // optional, id of an other target
"as_target_owner" (boolean) // (default: true) add your account as owner of the page
}
200
Headers
Content-Type: application/json
Body
{
"id": (string),
"displayname": (string),
"category": {
"id": (string),
"displayname": (string)
},
"images": {
"profile": {
"url": (string) // Image-URL
}
},
"premium": (boolean),
"verified": (boolean),
"secret": (boolean),
"stats": {
"amountFollowers": (int),
"amountFollows": (int),
"amountStomtsCreated": (int),
"amountStomtsReceived": (int)
},
"description": (string),
"websites": [
"link": (string)
]
}
Get a Target ¶
Get a TargetGET/targets/{target_id}
Example URI
- target_id
string
(required) Example: stomtThe unique slug of the target
200
Headers
Content-Type: application/json
Body
{
"id": (string),
"displayname": (string),
"category": {
"id": (string),
"displayname": (string)
},
"images": {
"profile": {
"url": (string) // Image-URL
}
},
"premium": (boolean),
"verified": (boolean),
"secret": (boolean),
"stats": {
"amountFollowers": (int),
"amountFollows": (int),
"amountStomtsCreated": (int),
"amountStomtsReceived": (int)
},
"description": (string),
"websites": [
"link": (string)
]
}
Get Target Stomts ¶
Get Target StomtsGET/targets/{target_id}/stomts/{type}/{secondType}{?newer_than}
Example URI
- target_id
string
(required) Example: stomtThe unique slug of the target
- type
string
(optional) Example: createdWhat to show: received or created stomts?
Choices:
received
created
top
- secondType
string
(optional) Example: positiveAll of type
type
or just the negative or positive ones?Choices:
positive
negative
- newer_than
string
(optional) Example: 1448911397Only stomts newer than the unix-timestamp will be returned
200
Headers
Content-Type: application/json
Body
[
A array of stomts (see "Stomts" for further information)
]
Update a Target ¶
Update a TargetPUT/targets/{target_id}
[LOGIN REQUIRED]
Example URI
- target_id
string
(required) Example: stomtThe unique slug of the target
Headers
Content-Type: application/json
Body
{
"displayname": (string),
"password": (string) // only for the own account
}
200
Headers
Content-Type: application/json
Body
{
"id": (string),
"displayname": (string),
"category": {
"id": (string),
"displayname": (string)
},
"images": {
"profile": {
"url": (string) // Image-URL
}
},
"premium": (boolean),
"verified": (boolean),
"secret": (boolean),
"stats": {
"amountFollowers": (int),
"amountFollows": (int),
"amountStomtsCreated": (int),
"amountStomtsReceived": (int)
},
"description": (string),
"websites": [
"link": (string)
]
}
Images ¶
Images are uploaded in a specific context and Base64 encoded.
Upload Image ¶
Upload ImagePOST/images
We can upload images in different **{context}**s:
-
avatar
-
cover
(Cover image in targets profile) -
stomt
(Picture attached to a stomt)
Supported file formats: jpg, png, gif, bmp, tiff
Example URI
Headers
Content-Type: application/json
Body
{
"id": (string), // (optional) target-id to upload image for owend target
"images": {
"{context}": [
{
"data": (string) // Base64 encoded image (optional)
"url": (string) // External image url (optional) - enables image-upload via URL
}
]
}
}
200
Headers
Content-Type: application/json
Body
{
"images": {
"{context}": {
"name": (string), // You'll need the name to append it to the stomt
"thumb": (string), // (Optional) only if a thumbnail exists (e.g. for GIFs)
"url": (string) // URL of the origin image
} // (if multiple images were submitted an array of images returns)
}
}
404
Headers
Content-Type: application/json
Body
If the given url is not readable.
Files ¶
Files are uploaded in a specific context and Base64 encoded.
Upload File ¶
Upload FilePOST/files
We can upload images in different **{context}**s:
stomt
(Files attached to a stomt)
Supported file formats: txt, log, zip
Example URI
Headers
Content-Type: application/json
Body
{
"files": {
"{context}": [ // Typically "stomt"
{
"data": (string), // Base64 encoded file (required)
"filename": (string) // Custom name e.g. user_actions.log (optional)
}
]
}
}
200
Headers
Content-Type: application/json
Body
{
"files": {
"{context}": {
"file_uid": (string), // You'll need the file_id to append it to the stomt
"url": (string) // Access the uploaded file here
} // (if multiple files were submitted an array of files returns)
}
}
404
Headers
Content-Type: application/json
Body
If the given url is not readable.