STOMT API v2.11.260

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
Create a target page on stomt.
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 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`

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

After log in you’ll receive an authorisation_code and a state value.
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:

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

POST https://rest.stomt.com/stomts

Request

HideShow

Headers

Content-Type: application/json

Body

{
    "text":         (string),   // (required)
    "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
    "positive":           (boolean),
    "text":               (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, ...
    "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
    "positive":           (boolean),
    "text":               (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, ...
    "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 ¶

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.

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 Target
GET`/search/{?q}`

Example URI

GET https://rest.stomt.com/search/?q=iPhone

URI Parameters

HideShow

q: string (required) Example: iPhone
Term to search for

Response 200

HideShow

Headers

Content-Type: application/json

Body

{
    "targets": [
        {
            "src_id":   (string),
            "src":      (string),
            "...":      (...)     // Target information
        }
    ]
}

Search Stomts ¶

Search Stomts
GET`/search/stomts/{?q}{?at}{?to}{?from}{?has}{?is}{?label}{?hashtag}`

Example URI

GET https://rest.stomt.com/search/stomts/?q=landing?at=stomt?to=stomt,stomt-api?from=lex?has=image,!reaction?is=like?label=todo,bug?hashtag=fun,more

URI Parameters

HideShow

q: string (optional) Example: landing
Term 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: like
Either 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: newest
Sort results. Possible orders are available: popular, newest, oldest, text, newest_comment, oldest_comment, newest_reaction, oldest_reaction, newest_vote, oldest_vote.

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
    Array of stomts
]

Search Hashtags ¶

Search Hashtags
GET`/search/hashtags{?q}`

Example URI

GET https://rest.stomt.com/search/hashtags?q=great

URI Parameters

HideShow

q: string (optional) Example: great
Search hashtags similar to query

Response 200

HideShow

Headers

Content-Type: application/json

Body

[
    A array of hashtag strings
]

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
type: string (required)
The requested file format (csv, xls, xlsx, …)
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.

Request/Response format ¶

Must Read (3 min) ¶

1. APP ID ¶

How to obtain an appid ¶

2. Requests that require authentication ¶

3. Standard Response Format ¶

4. Pagination ¶

5. Test Environment / stomt Sandbox ¶

6. Feedback ¶

Authentication ¶

Normal Credential flow ¶

Facebook Connect flow ¶

Reddit Connect flow ¶

Twitter Connect flow ¶

Anonym Account ¶

Register an User ¶

Register an UserPOST/authentication

Example URI

Headers

Body

Headers

Body

Login ¶

LoginPOST/authentication/session

Example URI

Headers

Body

Headers

Body

Headers

Body

Headers

Body

Logout ¶

LogoutDELETE/authentication/session

Example URI

Headers

Body

OAuth AuthorisationCode Grant ¶

oAuth LoginGET/authentication/authorize

Example URI

Headers

Check availability ¶

Check availabilityGET/authentication/checkAvailability{?property}{?value}

Example URI

Headers

Body

Suggest usernames based on displayname ¶

Suggest usernamesGET/authentication/suggestedUsernames?displayname

Example URI

Headers

Body

Verify E-mail ¶

Verify E-mailPUT/authentication

Example URI

Headers

Body

Headers

Body

Forgot password ¶

Forgot passwordPOST/authentication/forgotpassword

Example URI

Headers

Body

Headers

Body

Reset password ¶

Reset passwordPOST/authentication/resetpassword

Example URI

Headers

Body

Headers

Body

Stomts ¶

Creates a Stomt ¶

Creates a StomtPOST/stomts

Example URI

Headers

Body

Headers

Must Read (3 min)

1. APP ID

How to obtain an `appid`

2. Requests that require authentication

3. Standard Response Format

4. Pagination

5. Test Environment / stomt Sandbox

6. Feedback

Normal Credential flow

Facebook Connect flow

Reddit Connect flow

Twitter Connect flow

Anonym Account

Register an User
POST`/authentication`

Login
POST`/authentication/session`

Logout
DELETE`/authentication/session`

oAuth Login
GET`/authentication/authorize`

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

Suggest usernames
GET`/authentication/suggestedUsernames?displayname`

Verify E-mail
PUT`/authentication`

Forgot password
POST`/authentication/forgotpassword`

Reset password
POST`/authentication/resetpassword`

Creates a Stomt
POST`/stomts`

Read a Stomt
GET`/stomts/`

Delete a Stomt
DELETE`/stomts/`

Create Stomt Agreement
POST`/stomts/{stomt_id}/agreements`

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

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

Create a comment
POST`/stomts/{stomt_id}/comments`

Read Stomt Comments
GET`/stomts/{stomt_id}/comments`

Edit a comment
PUT`/stomts/{stomt_id}/comments/{comment_id}`

Deletes a single comment
DELETE`/stomts/{stomt_id}/comments/{comment_id}`

Vote on a Comment
POST`/stomts/{stomt_id}/comments/{comment_id}/votes`

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