STOMT API v2.11.376

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:

• 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 ¶

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

Content-Type: application/json

{
    // 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 
}

Content-Type: application/json

{
    "accesstoken":      (string),
    "refreshtoken":     (string),
    "user":             (userobject),
    "newUser":          (boolean)       // only true if it is the first login using facebook connect
}

Content-Type: application/json

{
  "data": [],
  "error": "Account not found.",
  "meta": []
}

Content-Type: application/json

{
  "data": [],
  "error": "Wrong password.",
  "meta": []
}

Content-Type: application/json

{
  "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.

Content-Type: application/json

{
    "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
    },
}

Content-Type: application/json

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

Content-Type: application/json

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

Content-Type: application/json

{
    "success" : (boolean)
}

Content-Type: application/json

{
    "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.

Content-Type: application/json

{
    "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
}

Content-Type: application/json

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

Content-Type: application/json

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

Content-Type: application/json

[
    A array of stomts (see "Stomts" for further information)
]

Content-Type: application/json

{
    "displayname": (string),
    "password":    (string)  // only for the own account
}

Content-Type: application/json

{
    "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.

Content-Type: application/json

{
    "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
            }
        ]
    }
}

Content-Type: application/json

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

Content-Type: application/json

If the given url is not readable.

Files ¶

Files are uploaded in a specific context and Base64 encoded.

Content-Type: application/json

{
    "files": {
        "{context}": [                  // Typically "stomt"
            {
                "data":     (string),   // Base64 encoded file (required)
                "filename": (string)    // Custom name e.g. user_actions.log (optional)
            }
        ]
    }
}

Content-Type: application/json

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

Content-Type: application/json

If the given url is not readable.