Back to top

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

  1. Register on www.stomt.com

  2. Create a target page on stomt.

  3. 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:

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

  1. Register an user via POST req. to /authentication/

  2. Get an access token via POST req. to /authentication/session

Facebook Connect flow

  1. Retrieve a Login URL by GET /authentication/facebook/url

  2. Redirect the user to the URL you obtained in (1)

  3. POST retrieved code and state and login_method:facebook to /authentication/session

Reddit Connect flow

  1. Get an Auth-URL per GET /authentication/reddit/authorizationurl

  2. Redirect the user to the URL you obtained in (1)

  3. POST retrieved code and state and login_method:reddit to /authentication/session

Twitter Connect flow

  1. Retrieve a Login URL by GET /authentication/twitter/url

  2. Redirect the user to the URL you obtained in (1)

  3. 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.

  1. Get an access token by performing any POST request which is flagged with [ANONYM]
  2. Use this token for all further requests
  3. 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 User
POST/authentication

Example URI

POST https://rest.stomt.com/authentication
Request
HideShow
Headers
Content-Type: application/json
Body
{
    "username": (string),
    "email":    (string),
    "password": (string),
    "displayname": (string),
    "message": (string)
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "accesstoken":      (string),
    "refreshtoken":     (string),
    "user":             (userobject),
    "newuser":          true
}

Login

Login
POST/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

POST https://rest.stomt.com/authentication/session
Request
HideShow
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 
}
Response  200
HideShow
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
}
Response  404
HideShow

Email/Username does not exist

(full response body, because data is empty)

Headers
Content-Type: application/json
Body
{
  "data": [],
  "error": "Account not found.",
  "meta": []
}
Response  403
HideShow

Wrong Password

(full response body, because data is empty)

Headers
Content-Type: application/json
Body
{
  "data": [],
  "error": "Wrong password.",
  "meta": []
}

Logout

Logout
DELETE/authentication/session

[LOGIN REQUIRED]

Example URI

DELETE https://rest.stomt.com/authentication/session
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "success": true
}

OAuth AuthorisationCode Grant

oAuth Login
GET/authentication/authorize

  1. Guide the user to /authentication/authorize?client_id={YOUR APPID}&redirect_uri={YOUR REDIRECT URI}

Determines where the response is sent. The value of this parameter must exactly match one of the values that appear in the Credentials page in the stomt Developer Center (including the http or https scheme, case, and trailing slash). You may choose between urn:ietf:wg:oauth:2.0:oob, urn:ietf:wg:oauth:2.0:oob:auto, or an http://localhost port

  1. After log in you’ll receive an authorisation_code and a state value.

  2. Make a POST request to /authentication/authorize/token and the authorisation_code and state in the JSON-Body to retrieve a session (contains access_token, refresh_token)

Example URI

GET https://rest.stomt.com/authentication/authorize
Response  200
HideShow
Headers
Content-Type: text/html

Check availability

Check availability
GET/authentication/checkAvailability{?property}{?value}

Check if displayname or email is still available

Example URI

GET https://rest.stomt.com/authentication/checkAvailability?property=username?value=Max_Francy
URI Parameters
HideShow
property
string (optional) Example: username

Check for existing username or email

value
string (optional) Example: Max_Francy

Value to check

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "success" : (boolean) // true = available
}

Suggest usernames based on displayname

Suggest usernames
GET/authentication/suggestedUsernames?displayname

Suggests possible and free usernames based on the given displayname (former called fullname)

Example URI

GET https://rest.stomt.com/authentication/suggestedUsernames?displayname
URI Parameters
HideShow
displayname
string (required) Example: Hans%20Wurst

Displayname

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  "hanshans",
  "hansWurst",
  "WurstHans",
  "Hans23"
]

Verify E-mail

Verify E-mail
PUT/authentication

Verify the users email address. The user gets a link with /verify/{verification_code}

Example URI

PUT https://rest.stomt.com/authentication
Request
HideShow
Headers
Content-Type: application/json
Body
{
    "verification_code":  (string)
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "accesstoken":      (string),
    "refreshtoken":     (string),
    "user":             (userobject),
    "newUser":          false
}

Forgot password

Forgot password
POST/authentication/forgotpassword

Sends the user an email to reset his password

Example URI

POST https://rest.stomt.com/authentication/forgotpassword
Request
HideShow
Headers
Content-Type: application/json
Body
{
    "usernameoremail": (string)
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "success": true
}

Reset password

Reset password
POST/authentication/resetpassword

Resets the users password and responds with a new session

Example URI

POST https://rest.stomt.com/authentication/resetpassword
Request
HideShow
Headers
Content-Type: application/json
Body
{
    "resetcode":    (string),
    "newpassword":  (string)
}
Response  200
HideShow
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 Stomt
POST/stomts

[LOGIN or ANONYM]

This is how the process works:

  1. The user selects between “I wish” (positive=false) and “I like”(positive=true)

  2. The user searches for a target to get the target_id

Example URI

POST https://rest.stomt.com/stomts
Request
HideShow
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
    },
}
Response  200
HideShow
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 Stomt
GET/stomts/

Example URI

GET https://rest.stomt.com/stomts/
URI Parameters
HideShow
stomt_id (required, string, `i_like_stomt_so_much`)
string (required) 

slug of a stomt

Response  200
HideShow
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 Stomt
DELETE/stomts/

[LOGIN or ANONYM]

Example URI

DELETE https://rest.stomt.com/stomts/
URI Parameters
HideShow
stomt_id (required, string, `i_like_stomt_so_much`)
string (required) 

slug of a stomt

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "success" : (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 Agreement
POST/stomts/{stomt_id}/agreements

[LOGIN or ANONYM]

Example URI

POST https://rest.stomt.com/stomts/because-they-have-hashtags/agreements
URI Parameters
HideShow
stomt_id
string (required) Example: because-they-have-hashtags

id of a stomt

Request
HideShow
Headers
Content-Type: application/json
Body
{
    "positive": (boolean),  // true = disagreement, false = agreement
    "anonym":   (boolean)   // hide user from other (default: false)
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "success": true
}

Delete Stomt Agreement

Delete Stomt Agreement
DELETE/stomts/{stomt_id}/agreements

[LOGIN or ANONYM]

Example URI

DELETE https://rest.stomt.com/stomts/because-they-have-hashtags/agreements
URI Parameters
HideShow
stomt_id
string (required) Example: because-they-have-hashtags

id of a stomt

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "success": true
}

Get stomt Voters

Get stomt Voters
GET/stomts/{stomt_id}/agreements

Example URI

GET https://rest.stomt.com/stomts/because-they-have-hashtags/agreements
URI Parameters
HideShow
stomt_id
string (required) Example: because-they-have-hashtags

id of a stomt

Response  200
HideShow
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 comment
POST/stomts/{stomt_id}/comments

[LOGIN REQUIRED]

This is how the process works:

Example URI

POST https://rest.stomt.com/stomts/because-they-have-hashtags/comments
URI Parameters
HideShow
stomt_id
string (required) Example: because-they-have-hashtags

id of a stomt

Request
HideShow
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
}
Response  200
HideShow
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 Comments
GET/stomts/{stomt_id}/comments

Example URI

GET https://rest.stomt.com/stomts/because-they-have-hashtags/comments
URI Parameters
HideShow
stomt_id
string (required) Example: because-they-have-hashtags

id of a stomt

Response  200
HideShow
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 comment
PUT/stomts/{stomt_id}/comments/{comment_id}

[LOGIN REQUIRED]

This is how the process works:

Example URI

PUT https://rest.stomt.com/stomts/because-they-have-hashtags/comments/dbl6di7lbd6liqw7bdzi
URI Parameters
HideShow
stomt_id
string (required) Example: because-they-have-hashtags

id of a stomt

comment_id
string (required) Example: dbl6di7lbd6liqw7bdzi

hashid of a comment

Request
HideShow
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
}
Response  200
HideShow
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 comment
DELETE/stomts/{stomt_id}/comments/{comment_id}

[LOGIN REQUIRED]

Example URI

DELETE https://rest.stomt.com/stomts/because-they-have-hashtags/comments/7n5c62n75v2n6o5fn5
URI Parameters
HideShow
stomt_id
string (required) Example: because-they-have-hashtags

id of a stomt

comment_id
string (required) Example: 7n5c62n75v2n6o5fn5

hashid of a comment

Response  200
HideShow
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 Comment
POST/stomts/{stomt_id}/comments/{comment_id}/votes

[LOGIN REQUIRED]

Example URI

POST https://rest.stomt.com/stomts/because-they-have-hashtags/comments/7n5c62n75v2n6o5fn5/votes
URI Parameters
HideShow
stomt_id
string (required) Example: because-they-have-hashtags

id of a stomt

comment_id
string (required) Example: 7n5c62n75v2n6o5fn5

hashid of a comment

Request
HideShow
Headers
Content-Type: application/json
Body
{
    "positive": (boolean)  // true = agreement, false = disagreement
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "success": true
}

Revoke a Vote

Revoke a Vote
DELETE/stomts/{stomt_id}/comments/{comment_id}/votes

[LOGIN REQUIRED]

Example URI

DELETE https://rest.stomt.com/stomts/because-they-have-hashtags/comments/7n5c62n75v2n6o5fn5/votes
URI Parameters
HideShow
stomt_id
string (required) Example: because-they-have-hashtags

id of a stomt

comment_id
string (required) Example: 7n5c62n75v2n6o5fn5

hashid of a comment

Response  200
HideShow
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 stomt
POST/stomts/{stomt_id}/labels

Example URI

POST https://rest.stomt.com/stomts/because-they-have-hashtags/labels
URI Parameters
HideShow
stomt_id
string (required) Example: because-they-have-hashtags

id of a stomt

Request
HideShow
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)
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "name":             (string),
    "color":            (string)
}

Unlabel a stomt

Unlabel a stomt
DELETE/stomts/{stomt_id}/labels/{label}{?as_target_owner}

Example URI

DELETE https://rest.stomt.com/stomts/because-they-have-hashtags/labels/test?as_target_owner=true
URI Parameters
HideShow
stomt_id
string (required) Example: because-they-have-hashtags

id of a stomt

label
string (required) Example: test

the label to be removed

as_target_owner
boolean (optional) Example: true

Remove private or target-label

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "success" : (boolean)
}

Label a list of stomts

Label a list of stomts
POST/stomts/labels/{labelName}

Example URI

POST https://rest.stomt.com/stomts/labels/good-wishes
URI Parameters
HideShow
labelName
string (required) Example: good-wishes

name of the label

Request
HideShow
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)
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "success":             (boolean)
}

Remove label from list of stomts

Remove labels
DELETE/stomts/labels/{labelName}{?stomts}{&as_target_owner}

Example URI

DELETE https://rest.stomt.com/stomts/labels/test?stomts=id1,id2,id3&as_target_owner=true
URI Parameters
HideShow
labelName
string (required) Example: test

the label to be removed

stomts
array (required) Example: id1,id2,id3

list of stomt slugs

as_target_owner
boolean (optional) Example: true

(default: true) remove private or target-label

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "success" : (boolean)
}

Feeds

Feeds

Get a specific feed
GET/feeds/{type}{?newer_than}

[LOGIN REQUIRED]

Example URI

GET https://rest.stomt.com/feeds/home?newer_than=1448911397
URI Parameters
HideShow
type
string (required) Example: home

Receive the feed in form of a stomt-collection

Choices: home discover

newer_than
string (optional) Example: 1448911397

Only stomts newer than the unix-timestamp will be returned

Response  200
HideShow
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 Target
POST/targets

[LOGIN REQUIRED]

Example URI

POST https://rest.stomt.com/targets
Request
HideShow
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
}
Response  200
HideShow
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-Request
POST/targets/preflight

Example URI

POST https://rest.stomt.com/targets/preflight
Request
HideShow
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"
}
Response  200
HideShow
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 Target
GET/targets/{target_id}

Example URI

GET https://rest.stomt.com/targets/stomt
URI Parameters
HideShow
target_id
string (required) Example: stomt

The unique slug of the target

Response  200
HideShow
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 Stomts
GET/targets/{target_id}/stomts/{type}/{secondType}{?newer_than}

Example URI

GET https://rest.stomt.com/targets/stomt/stomts/created/positive?newer_than=1448911397
URI Parameters
HideShow
target_id
string (required) Example: stomt

The unique slug of the target

type
string (optional) Example: created

What to show: received or created stomts?

Choices: received created top

secondType
string (optional) Example: positive

All of type typeor just the negative or positive ones?

Choices: positive negative

newer_than
string (optional) Example: 1448911397

Only stomts newer than the unix-timestamp will be returned

Response  200
HideShow
Headers
Content-Type: application/json
Body
[
    A array of stomts (see "Stomts" for further information)
]

Update a Target

Update a Target
PUT/targets/{target_id}

[LOGIN REQUIRED]

Example URI

PUT https://rest.stomt.com/targets/stomt
URI Parameters
HideShow
target_id
string (required) Example: stomt

The unique slug of the target

Request
HideShow
Headers
Content-Type: application/json
Body
{
    "displayname": (string),
    "password":    (string)  // only for the own account
}
Response  200
HideShow
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 Application
GET/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

GET https://rest.stomt.com/targets/stomt/applications
URI Parameters
HideShow
target_id
string (required) Example: stomt

The unique slug of the target

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "id":           (string), // the appid you need for you external system
    "type":         (string),
    "target":       (targetobject)
}

Create Application

Create Application
POST/targets/{target_id}/applications

[LOGIN REQUIRED, TARGET OWNER]

Example URI

POST https://rest.stomt.com/targets/stomt/applications
URI Parameters
HideShow
target_id
string (required) Example: stomt

The unique slug of the target the application should be created for

Request
HideShow
Headers
Content-Type: application/json
Body
{
    "type":   (string), // (default: 'custom') options: 'Javascript-Widget', 'Unity', 'Unreal', ...
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
    "id":           (string), // the appid you need for you external system
    "type":         (string),
    "target":       (targetobject)
}

Delete Application

Delete Application
DELETE/targets/{target_id}/applications/{application_id}

[LOGIN REQUIRED, TARGET OWNER]

Example URI

DELETE https://rest.stomt.com/targets/stomt/applications/Jasdrg123lasdas12easda
URI Parameters
HideShow
target_id
string (required) Example: stomt

The unique slug of the target the application belongs to

application_id
string (required) Example: Jasdrg123lasdas12easda

The unique id of the application

Request
HideShow
Headers
Content-Type: application/json
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "success": true
}

Target Following

Get Followers

Get Followers
GET/targets/{target_id}/followers

Example URI

GET https://rest.stomt.com/targets/stomt/followers
URI Parameters
HideShow
target_id
string (required) Example: stomt

The unique slug of the target

Response  200
HideShow
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 Target
POST/targets/{target_id}/followers

[LOGIN REQUIRED]

Example URI

POST https://rest.stomt.com/targets/stomt/followers
URI Parameters
HideShow
target_id
string (required) Example: stomt

The unique slug of the target

Request
HideShow
Headers
Content-Type: application/json
Body
// empty
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "success": true
}

Unfollow a Target

Unfollow a Target
DELETE/targets/{target_id}/followers

[LOGIN REQUIRED]

Example URI

DELETE https://rest.stomt.com/targets/stomt/followers
URI Parameters
HideShow
target_id
string (required) Example: stomt

The unique slug of the target

Request
HideShow
Headers
Content-Type: application/json
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "success": true
}

Get Follows

Get Follows
GET/targets/{target_id}/follows

Example URI

GET https://rest.stomt.com/targets/stomt/follows
URI Parameters
HideShow
target_id
string (required) Example: stomt

The unique slug of the target

Response  200
HideShow
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 Invitations
GET/targets/{target_id}/invitations

[LOGIN REQUIRED, TARGET OWNER]

Example URI

GET https://rest.stomt.com/targets/stomt/invitations
URI Parameters
HideShow
target_id
string (required) Example: stomt

The unique slug of the target

Response  200
HideShow
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 Invitation
POST/targets/{target_id}/invitations

[LOGIN REQUIRED, TARGET OWNER]

Example URI

POST https://rest.stomt.com/targets/stomt/invitations
URI Parameters
HideShow
target_id
string (required) Example: stomt

The unique slug of the target

Request
HideShow
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
}
Response  200
HideShow
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 validity
GET/targets/{target_id}/invitations/{code}

Example URI

GET https://rest.stomt.com/targets/stomt/invitations/RK41nMUtaQ5X7aH88
URI Parameters
HideShow
target_id
string (required) Example: stomt

The unique slug of the target

code
string (required) Example: RK41nMUtaQ5X7aH88

The code of the invitation

Response  200
HideShow
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 Stomts
GET/targets/users/{?q}{?has}{?offset}{?limit}{?orderBy}

Example URI

GET https://rest.stomt.com/targets/users/?q=landing?has=image,!reaction?offset=20?limit=20?orderBy=mostVotes
URI Parameters
HideShow
q
string (optional) Example: landing

Term 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: 20

Pagination offset

limit
integer (optional) Example: 20

Pagination limit

orderBy
string (optional) Example: mostVotes

Order of the users. Available order types are: mostVotes, leastVotes, mostReactions, leastReactions, mostStomts, leastStomts, mostComments, leastComments.

Response  200
HideShow
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

Get all Categories

Get all Categories
GET/categories

Example URI

GET https://rest.stomt.com/categories
Response  200
HideShow
Headers
Content-Type: application/json
Body
[{
   "id":            (string),
   "displayname":   (string)
}]

Notifications

Get Notifications

Get Notifications
GET/notifications{?unseen}{?last_notification}{?offset}{?limit}

[LOGIN REQUIRED]

Example URI

GET https://rest.stomt.com/notifications?unseen=true?last_notification=timestamp?offset=0?limit=7
URI Parameters
HideShow
unseen
boolean (optional) Example: true

Set true to get only unseen notifications

last_notification
string (optional) Example: timestamp

Add a timestamp to get only notifications created after the provided timestamp

offset
integer (optional) Example: 0

Load more notifications for pagination (default: 0)

limit
integer (optional) Example: 7

Load more notifications at once (default: 7)

Response  200
HideShow
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 Notifications
PUT/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

PUT https://rest.stomt.com/notifications
Request
HideShow
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
}]
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "success": true
}

Images

Images are uploaded in a specific context and Base64 encoded.

Upload Image

Upload Image
POST/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

POST https://rest.stomt.com/images
Request
HideShow
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
            }
        ]
    }
}
Response  200
HideShow
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)
    }
}
Response  404
HideShow
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 File
POST/files

We can upload images in different **{context}**s:

  • stomt (Files attached to a stomt)

Supported file formats: txt, log, zip

Example URI

POST https://rest.stomt.com/files
Request
HideShow
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)
            }
        ]
    }
}
Response  200
HideShow
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)
    }
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
If the given url is not readable.

Export

Endpoint to retrieve stomts in a specified format

Retrieve exported Stomts
GET/exports/stomts?accesstoken&type&stomts

Example URI

GET https://rest.stomt.com/exports/stomts?accesstoken&type&stomts
URI Parameters
HideShow
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

Response  200
HideShow
Headers
Content-Type: application/json
Body
The requested file.

Endpoint to retrieve users in a specified format

Retrieve exported Users
GET/exports/users?accesstoken&type&users&target

Example URI

GET https://rest.stomt.com/exports/users?accesstoken&type&users&target
URI Parameters
HideShow
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

Response  200
HideShow
Headers
Content-Type: application/json
Body
The requested file.

Generated by aglio on 26 Feb 2021