Back to top

STOMT API v2.11.376

This is the official stomt documentation. Use it to make the world a little bit better.

Request/Response format

Read this first!

To keep the API endpoint flexible, maintainable and extendable, we defined a standard set of custom HTTP headers and a fix output format. In this section you’ll learn how requests are build and how responses will always look like.

Must Read (3 min)

1. APP ID

This header has to be sent with each request you make.

appid:       (string) // specific id for your app, website or what you build

How to obtain an appid

  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

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
}

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)
}

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)
    }
}

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)
    ]
}

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)
    ]
}

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.

Generated by aglio on 29 Mar 2021