STOMT API v2.11.358
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
Register an User ¶
Register an UserPOST/authentication
Example URI
Headers
Content-Type: application/json
Body
{
"username": (string),
"email": (string),
"password": (string),
"displayname": (string),
"message": (string)
}
200
Headers
Content-Type: application/json
Body
{
"accesstoken": (string),
"refreshtoken": (string),
"user": (userobject),
"newuser": true
}
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": []
}
Logout ¶
LogoutDELETE/authentication/session
[LOGIN REQUIRED]
Example URI
200
Headers
Content-Type: application/json
Body
{
"success": true
}
Check availability ¶
Check availabilityGET/authentication/checkAvailability{?property}{?value}
Check if displayname or email is still available
Example URI
- property
string
(optional) Example: usernameCheck for existing username or email
- value
string
(optional) Example: Max_FrancyValue to check
200
Headers
Content-Type: application/json
Body
{
"success" : (boolean) // true = available
}
Suggest usernames based on displayname ¶
Suggest usernamesGET/authentication/suggestedUsernames?displayname
Suggests possible and free usernames based on the given displayname (former called fullname)
Example URI
- displayname
string
(required) Example: Hans%20WurstDisplayname
200
Headers
Content-Type: application/json
Body
[
"hanshans",
"hansWurst",
"WurstHans",
"Hans23"
]
Verify E-mail ¶
Verify E-mailPUT/authentication
Verify the users email address. The user gets a link with /verify/{verification_code}
Example URI
Headers
Content-Type: application/json
Body
{
"verification_code": (string)
}
200
Headers
Content-Type: application/json
Body
{
"accesstoken": (string),
"refreshtoken": (string),
"user": (userobject),
"newUser": false
}
Forgot password ¶
Forgot passwordPOST/authentication/forgotpassword
Sends the user an email to reset his password
Example URI
Headers
Content-Type: application/json
Body
{
"usernameoremail": (string)
}
200
Headers
Content-Type: application/json
Body
{
"success": true
}
Reset password ¶
Reset passwordPOST/authentication/resetpassword
Resets the users password and responds with a new session
Example URI
Headers
Content-Type: application/json
Body
{
"resetcode": (string),
"newpassword": (string)
}
200
Headers
Content-Type: application/json
Body
{
"accesstoken": (string),
"refreshtoken": (string),
"user": (userobject),
"newUser": false
}
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)
}
}
Stomt Agreements ¶
A single agreement object.
In case the user already agreed and wants to revoke his (dis-)agreement, we do not want you to update the positive-attribute of the existing agreement via PUT. Just DELETE the old (dis-)agreement and POST a new one.
Create Stomt Agreement ¶
Create Stomt AgreementPOST/stomts/{stomt_id}/agreements
[LOGIN or ANONYM]
Example URI
- stomt_id
string
(required) Example: because-they-have-hashtagsid of a stomt
Headers
Content-Type: application/json
Body
{
"positive": (boolean), // true = disagreement, false = agreement
"anonym": (boolean) // hide user from other (default: false)
}
200
Headers
Content-Type: application/json
Body
{
"success": true
}
Delete Stomt Agreement ¶
Delete Stomt AgreementDELETE/stomts/{stomt_id}/agreements
[LOGIN or ANONYM]
Example URI
- stomt_id
string
(required) Example: because-they-have-hashtagsid of a stomt
200
Headers
Content-Type: application/json
Body
{
"success": true
}
Get stomt Voters ¶
Get stomt VotersGET/stomts/{stomt_id}/agreements
Example URI
- stomt_id
string
(required) Example: because-they-have-hashtagsid of a stomt
200
Headers
Content-Type: application/json
Body
{
"up": [
// Target Basic
],
"down": [
// Target Basic
]
}
Stomt Comments ¶
A stomt can have comments, which themselves can have comments again if a user replied to a comment. They all can be voted and at most one comment to a stomt can be marked as with a “state” (reaction, fulfilled, rejected).
Create a comment ¶
Create a commentPOST/stomts/{stomt_id}/comments
[LOGIN REQUIRED]
This is how the process works:
Example URI
- stomt_id
string
(required) Example: because-they-have-hashtagsid of a stomt
Headers
Content-Type: application/json
Body
{
"parent_id": (string|null), // hashid of the parent comment OR null
"text": (string), // comment text
"state": (string, optional), // state: reaction(null), fulfilled, rejected
"as_target": (string), // premium accounts can comment in the name of projects they own
"reaction": (boolean) // top level comments by the target owner can be marked as reaction
}
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)
}
}
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)
}
}
Edit a comment ¶
Edit a commentPUT/stomts/{stomt_id}/comments/{comment_id}
[LOGIN REQUIRED]
This is how the process works:
Example URI
- stomt_id
string
(required) Example: because-they-have-hashtagsid of a stomt
- comment_id
string
(required) Example: dbl6di7lbd6liqw7bdzihashid of a comment
Headers
Content-Type: application/json
Body
{
"anonym": (boolean), // Anonymous comment
"text": (string), // comment text
"state": (string), // state: reaction(null), fulfilled, rejected
"reaction": (boolean) // top level comments by the target owner can be marked as reaction
}
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)
}
}
Deletes a single comment ¶
Deletes a single commentDELETE/stomts/{stomt_id}/comments/{comment_id}
[LOGIN REQUIRED]
Example URI
- stomt_id
string
(required) Example: because-they-have-hashtagsid of a stomt
- comment_id
string
(required) Example: 7n5c62n75v2n6o5fn5hashid of a comment
200
Headers
Content-Type: application/json
Body
{
"success": true
}
Stomt Comment Votes ¶
A single vote on a comment
In case the user already voted and wants to revoke his voting, we do not want you to update the positive-attribute of the existing comment via PUT. Just DELETE the old voting and POST a new one.
Vote on a Comment ¶
Vote on a CommentPOST/stomts/{stomt_id}/comments/{comment_id}/votes
[LOGIN REQUIRED]
Example URI
- stomt_id
string
(required) Example: because-they-have-hashtagsid of a stomt
- comment_id
string
(required) Example: 7n5c62n75v2n6o5fn5hashid of a comment
Headers
Content-Type: application/json
Body
{
"positive": (boolean) // true = agreement, false = disagreement
}
200
Headers
Content-Type: application/json
Body
{
"success": true
}
Revoke a Vote ¶
Revoke a VoteDELETE/stomts/{stomt_id}/comments/{comment_id}/votes
[LOGIN REQUIRED]
Example URI
- stomt_id
string
(required) Example: because-they-have-hashtagsid of a stomt
- comment_id
string
(required) Example: 7n5c62n75v2n6o5fn5hashid of a comment
200
Headers
Content-Type: application/json
Body
{
"success": true
}
Stomt Labels ¶
stomts can have labels which can be managed in the targets profile. Labels can be archived or unarchived and they may be public or private. Users can create labels, too, which are only visible to them except they share the labels explicit URL.
Label a stomt ¶
Label a stomtPOST/stomts/{stomt_id}/labels
Example URI
- stomt_id
string
(required) Example: because-they-have-hashtagsid of a stomt
Headers
Content-Type: application/json
Body
{
"name": (string), // (required)
"color": (string), // (optional; default: #5EBEFF)
// This flag is only applied when you create a new label, existing
// labels will stay public/private as already defined
"public": (boolean), // (optional; default: false)
// Does the user act as private user and deletes his private label
// or does he act as target owner and removes a targets label?
"as_target_owner": (boolean) // (optional; default: false)
}
200
Headers
Content-Type: application/json
Body
{
"name": (string),
"color": (string)
}
Unlabel a stomt ¶
Unlabel a stomtDELETE/stomts/{stomt_id}/labels/{label}{?as_target_owner}
Example URI
- stomt_id
string
(required) Example: because-they-have-hashtagsid of a stomt
- label
string
(required) Example: testthe label to be removed
- as_target_owner
boolean
(optional) Example: trueRemove private or target-label
200
Headers
Content-Type: application/json
Body
{
"success" : (boolean)
}
Label a list of stomts ¶
Label a list of stomtsPOST/stomts/labels/{labelName}
Example URI
- labelName
string
(required) Example: good-wishesname of the label
Headers
Content-Type: application/json
Body
{
"stomts": (array), // (required) list of stomt slugs
"color": (string), // (optional; default: #5EBEFF)
// This flag is only applied when you create a new label, existing
// labels will stay public/private as already defined
"public": (boolean), // (optional; default: false)
// Does the user act as private user and deletes his private label
// or does he act as target owner and removes a targets label?
"as_target_owner": (boolean) // (optional; default: false)
}
200
Headers
Content-Type: application/json
Body
{
"success": (boolean)
}
Remove label from list of stomts ¶
Remove labelsDELETE/stomts/labels/{labelName}{?stomts}{&as_target_owner}
Example URI
- labelName
string
(required) Example: testthe label to be removed
- stomts
array
(required) Example: id1,id2,id3list of stomt slugs
- as_target_owner
boolean
(optional) Example: true(default: true) remove private or target-label
200
Headers
Content-Type: application/json
Body
{
"success" : (boolean)
}
Feeds ¶
Feeds ¶
Get a specific feedGET/feeds/{type}{?newer_than}
[LOGIN REQUIRED]
Example URI
- type
string
(required) Example: homeReceive the feed in form of a stomt-collection
Choices:
home
discover
- 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)
]
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)
]
}
Preflight-Request ¶
Preflight-RequestPOST/targets/preflight
Example URI
Headers
Content-Type: application/json
Body
{
// Currently only for Twitter (shorthandle = tw)
"src": (string), // Providers Shorthandle (e.g. "tw")
"src_id": (string) // username at the providers platform: e.g. twitter.com/stomt -> "stomt"
}
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)
]
}
Target Applications ¶
Applications are required to make use of the stomt API in an own external system.
Get Application ¶
Get ApplicationGET/targets/{target_id}/applications
[LOGIN REQUIRED, TARGET OWNER]
Retrieve all applications linked to the target. If the target is a user access all applications the user has access to.
Example URI
- target_id
string
(required) Example: stomtThe unique slug of the target
200
Headers
Content-Type: application/json
Body
{
"id": (string), // the appid you need for you external system
"type": (string),
"target": (targetobject)
}
Create Application ¶
Create ApplicationPOST/targets/{target_id}/applications
[LOGIN REQUIRED, TARGET OWNER]
Example URI
- target_id
string
(required) Example: stomtThe unique slug of the target the application should be created for
Headers
Content-Type: application/json
Body
{
"type": (string), // (default: 'custom') options: 'Javascript-Widget', 'Unity', 'Unreal', ...
}
200
Headers
Content-Type: application/json
Body
{
"id": (string), // the appid you need for you external system
"type": (string),
"target": (targetobject)
}
Delete Application ¶
Delete ApplicationDELETE/targets/{target_id}/applications/{application_id}
[LOGIN REQUIRED, TARGET OWNER]
Example URI
- target_id
string
(required) Example: stomtThe unique slug of the target the application belongs to
- application_id
string
(required) Example: Jasdrg123lasdas12easdaThe unique id of the application
Headers
Content-Type: application/json
200
Headers
Content-Type: application/json
Body
{
"success": true
}
Target Following ¶
Get Followers ¶
Get FollowersGET/targets/{target_id}/followers
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": {
"avatar": {
"url": (string) // Image-URL
}
},
"stats": {
"amountFollowers": (int),
"amountFollows": (int),
"amountStomtsCreated": (int),
"amountStomtsReceived": (int)
}
}]
Follow a Target ¶
Follow a TargetPOST/targets/{target_id}/followers
[LOGIN REQUIRED]
Example URI
- target_id
string
(required) Example: stomtThe unique slug of the target
Headers
Content-Type: application/json
Body
// empty
200
Headers
Content-Type: application/json
Body
{
"success": true
}
Unfollow a Target ¶
Unfollow a TargetDELETE/targets/{target_id}/followers
[LOGIN REQUIRED]
Example URI
- target_id
string
(required) Example: stomtThe unique slug of the target
Headers
Content-Type: application/json
200
Headers
Content-Type: application/json
Body
{
"success": true
}
Get Follows ¶
Get FollowsGET/targets/{target_id}/follows
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": {
"avatar": {
"url": (string) // Image-URL
}
},
"stats": {
"amountFollowers": (int),
"amountFollows": (int),
"amountStomtsCreated": (int),
"amountStomtsReceived": (int)
}
}]
Target Invitations ¶
Get Invitations ¶
Get InvitationsGET/targets/{target_id}/invitations
[LOGIN REQUIRED, TARGET OWNER]
Example URI
- target_id
string
(required) Example: stomtThe unique slug of the target
200
Headers
Content-Type: application/json
Body
[{
"link": (string), // signup link for the new user
"code": (string),
"invited_to": (object),
"invited_to_type": (string),
"invited_as_owner": (boolean),
"invited_by": (targetobject),
"used": (boolean),
"used_by": (targetobject) // if not used = null
}]
Create Invitation ¶
Create InvitationPOST/targets/{target_id}/invitations
[LOGIN REQUIRED, TARGET OWNER]
Example URI
- target_id
string
(required) Example: stomtThe unique slug of the target
Headers
Content-Type: application/json
Body
{
"invite_as_owner": (boolean), // (default: true) invited user will be owner of the page
"role_id": (int), // (optional) apply this role to the new owner
}
200
Headers
Content-Type: application/json
Body
{
"link": (string), // signup link for the new user
"code": (string),
"invited_to": (object),
"invited_to_type": (string),
"invited_as_owner": (boolean),
"invited_by": (targetobject),
"used": false,
"used_by": null
}
Check for validity ¶
Check for validityGET/targets/{target_id}/invitations/{code}
Example URI
- target_id
string
(required) Example: stomtThe unique slug of the target
- code
string
(required) Example: RK41nMUtaQ5X7aH88The code of the invitation
200
Headers
Content-Type: application/json
Body
{
"link": (string),
"code": (string),
"invited_to": (object),
"invited_to_type": (string),
"invited_as_owner": (boolean),
"invited_by": (targetobject),
"used": (boolean),
"used_by": (targetobject) // if not used = null
}
Target Users ¶
These endpoints deal with the users that are active on a target by posting stomts, comments or by voting.
Get target users ¶
Search StomtsGET/targets/users/{?q}{?has}{?offset}{?limit}{?orderBy}
Example URI
- q
string
(optional) Example: landingTerm to search for in user name
- has
string
(optional) Example: image,!reaction(list of keywords) Filter for users matching the criteria, the keywords can be negated by prefixing them with a “!”. Following keywords are available:
votes, comments, reactions, labels, stomts, data
- is
string
(optional) Example: anonym,!targetOwner(list of keywords) Filter for user types. Following keywords are available:
targetOwner, anonym, follower
- groups
string
(optional) Example: powerUser,!beginner(list of groups) Filter for users that belong to groups, groups can be negated
- offset
integer
(optional) Example: 20Pagination offset
- limit
integer
(optional) Example: 20Pagination limit
- orderBy
string
(optional) Example: mostVotesOrder of the users. Available order types are:
mostVotes, leastVotes, mostReactions, leastReactions, mostStomts, leastStomts, mostComments, leastComments
.
200
Headers
Content-Type: application/json
Body
[
Array of users with additional attributes
"amountStomtsOnTarget": (int), // number of stomts the user created
"amountVotesOnTarget": (int), // number of votes the user gave to other stomts
"amountUpVotesReceivedOnTarget": (int), // number of upvotes the user received
"amountCommentsOnTarget": (int), // number of comments the user wrote
"amountCommentsReceivedOnTarget": (int), // number of comments the user received
"amountReactionsOnTarget": (int), // number of reactions the user wrote
"amountReactionsReceivedOnTarget": (int), // number of reactions the user received
"groups": [
{
"name": (string)
}
]
]
Categories ¶
Notifications ¶
Get Notifications ¶
Get NotificationsGET/notifications{?unseen}{?last_notification}{?offset}{?limit}
[LOGIN REQUIRED]
Example URI
- unseen
boolean
(optional) Example: trueSet true to get only unseen notifications
- last_notification
string
(optional) Example: timestampAdd a timestamp to get only notifications created after the provided timestamp
- offset
integer
(optional) Example: 0Load more notifications for pagination (default:
0
)- limit
integer
(optional) Example: 7Load more notifications at once (default:
7
)
200
Headers
Content-Type: application/json
Body
[{
"id": (string),
"text": (string),
"goal" : {
"type": (string), // 'stomt' or 'target'
"target": (object) // target object if type is "target"
"stomt": (object) // target object if type is "stomt"
},
"created_at": (ISO 8601), // Timestamp in ISO 8601
"seen": (boolean), // false = unseen; true = seen
"clicked": (boolean) // false = unclicked; true = clicked
}]
Update Notifications ¶
Update NotificationsPUT/notifications
[LOGIN REQUIRED]
If notifications are seen by the user (e.g. the user views a notification overview) set the seen-attribute to true
.
If the user clicks/taps on a notification set the clicked-attribute to true
.
Example URI
Headers
Content-Type: application/json
Body
[{
"id": (string),
"seen": (boolean), // (optional) has notification been shown to the user
"clicked": (boolean) // (optional) has notification been clicked by the user
}]
200
Headers
Content-Type: application/json
Body
{
"success": true
}
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.
Search ¶
To use the result you need the src
and src_id
. Currently all results have src = s
, because all results represent existing targets in stomt. The src_id
is the targets id.
Search Target ¶
Search TargetGET/search/{?q}
Example URI
- q
string
(required) Example: iPhoneTerm to search for
200
Headers
Content-Type: application/json
Body
{
"targets": [
{
"src_id": (string),
"src": (string),
"...": (...) // Target information
}
]
}
Search Stomts ¶
Search StomtsGET/search/stomts/{?q}{?at}{?to}{?from}{?has}{?is}{?label}{?hashtag}
Example URI
- q
string
(optional) Example: landingTerm to search for in the stomt text
- at
string
(optional) Example: stomt(target-id) Only show stomts that belong in some way to the given target (Please us
at
instead of an@
-sign as request parameter)- to
string
(optional) Example: stomt,stomt-api(list of target-ids) Filter for stomts the targets have received directly
- from
string
(optional) Example: lex(list of target-ids) Filter for stomts created by these users
- has
string
(optional) Example: image,!reaction(list of keywords) Filter for stomts matching the criteria, the keywords can be negated by prefixing them with a “!”. Following keywords are available:
votes, comments, reaction, image, labels, url, file, data
- is
string
(optional) Example: likeEither filter for likes (
like
) or wishes (wish
)- label
string
(optional) Example: todo,bug(list of labels) Filter for stomts that contain all given labels, labels can be negated
- hashtag
string
(optional) Example: fun,more(list of hashtags) Filter for stomts that contain all given hashtags, hashtags can be negated
- lang
string
(optional) Example: de,!en(list of languages) Filter for stomts matching specific languages (ISO 639-1), languages can be prefixed with “!” to exclude stomts in this language.
- newer_than
string
(optional) Example: 2014-03-01T08:52:07+0000(date) Filter for stomts created after the specified date
- older_than
string
(optional) Example: 2014-03-01T08:52:07+0000(date) Filter for stomts created before the speciefied date
- orderBy
string
(optional) Example: newestSort results. Possible orders are available:
popular
,newest
,oldest
,text
,newest_comment
,oldest_comment
,newest_reaction
,oldest_reaction
,newest_vote
,oldest_vote
.
200
Headers
Content-Type: application/json
Body
[
Array of stomts
]
Export ¶
Endpoint to retrieve stomts in a specified format ¶
Retrieve exported StomtsGET/exports/stomts?accesstoken&type&stomts
Example URI
- accesstoken
string
(required)The access token of the current user session
- format
string
(required)The requested file format (csv, xls, xlsx, …) (was previously names ‘type’)
- stomts
string
(required)A comma separated list of stomt slugs
200
Headers
Content-Type: application/json
Body
The requested file.
Endpoint to retrieve users in a specified format ¶
Retrieve exported UsersGET/exports/users?accesstoken&type&users&target
Example URI
- accesstoken
string
(required)The access token of the current user session
- type
string
(required)The requested file format (csv, xls, xlsx, …)
- users
string
(required)A comma separated list of user ids
- target
string
(required)The id of the target the user data should be calculated from
200
Headers
Content-Type: application/json
Body
The requested file.