Skip to content

API Documentation (V2)

Jump to bottom Edit New page
ArtOfCode edited this page Aug 28, 2018 · 21 revisions

This page contains documentation for version 2.0 of the metasmoke API. If that's not what you're expecting, you're in the wrong place.

Authentication

Like 1.0, you need a key to access the API. Ping an admin to get one if you don't already have one. If you've previously been given a key but no longer have it, you should be able to access it at https://metasmoke.erwaysoftware.com/admin/keys/mine.

For write authentication, the same flow applies as for v1:

  • Send your user to https://metasmoke.erwaysoftware.com/oauth/request?key=YOUR_KEY_HERE.
  • If the user authorizes your app, they will be given a code to provide you. Ask them to enter this code, then:
  • Send a HTTP GET request to https://metasmoke.erwaysoftware.com/oauth/token?key=YOUR_KEY_HERE&code=THEIR_CODE_HERE. The response is a JSON object containing one key, token, the value of which is your write token. Include this as the token parameter on any requests that require it.

Filters

Filters have been totally reworked in V2 of the API; they really were that terrible in v1. Again, visit https://metasmoke.erwaysoftware.com/api/filters to create a filter, and include it as the filter parameter on any requests you need it for.

Filters are not quite immutable. If the server configuration remains the same, then the same filter will always represent the same fields. However, if the server configuration changes - such as to add a new field to the API - then filters will also change. If you're getting an SQL error on your requests, this is probably the cause - go recalculate your filters.

You can calculate filters programmatically if you wish: send a POST request to https://metasmoke.erwaysoftware.com/api/filters with the fields parameter set to an array of field names that you want to include (i.e. ['announcements.id', 'announcements.text', 'announcements.expiry']), and you will get back a JSON object containing the filter.

You may also include the filter-generation logic directly in your application if you really want; it's less complex than v1's, so that's not too much of a liability. Bear in mind, however, that if the metasmoke implementation changes you will need to push out an update to your implementation to match.

Pagination

Responses from the API are paginated (that is, a long list of results will be split into pages and only the first page of results returned; further pages may be fetched by additional requests specifying a page number). The has_more field in the response indicates whether or not more pages are available beyond the current page.

The default page size is 10 items; you can control this using the per_page parameter. To fetch pages beyond 1, specify the requested page number in the page parameter.

Routes

Routes marked with [W] are write routes; you must use a POST request and present a write token for these routes.

Path Description
Announcements
/api/v2.0/announcements
List all announcements.

Available tables: announcements
Output format:

{
    "items": [
        {
            "id": 25,
            "text": "Test API announcement",
            "expiry": "2017-12-13T19:00:00.000Z"
        }
    ],
    "has_more": true
}
/api/v2.0/announcements/active
List active (non-expired) announcements.

Available tables: announcements
Output format: identical to /announcements.
/api/v2.0/announcements/expired
List expired announcements.

Available tables: announcements
Output format: identical to /announcements.
/api/v2.0/announcements/create
[W] Create an announcement.

Available tables: N/A. All fields are returned. Filter is ignored.

Requires params: text and expiry. Requires core role.

Output format:

{
    "items": [
        {
            "id": 27,
            "text": "test from API",
            "expiry": "2017-01-01T00:00:00.000Z",
            "created_at": "2017-12-17T23:11:55.000Z",
            "updated_at": "2017-12-17T23:11:55.000Z"
        }
    ],
    "has_more": false
}
Apps
/api/v2.0/apps
List all apps.

Available tables: api_keys.
Output format:

{
    "items": [
        {
            "id": 21,
            "app_name": "thesecretmaster's app",
            "user_id": 298,
            "github_link": ""
        }
    ],
    "has_more": true
}
Comments
/api/v2.0/comments
List all comments.

Available tables: post_comments.
Output format:

{
    "items": [
        {
            "id": 2,
            "user_id": 1373,
            "text": "Some more words."
        }
    ],
    "has_more": true
}
/api/v2.0/comments/post/:id
List all comments on a specified post.

Available tables: post_comments.
Output format: identical to /comments.
/api/v2.0/comments/post/:id
[W] [Smokey] Add an automatic comment to a post.

This route is for use by SmokeDetector instances only.
Requires parameters: text, chat_user_id, and chat_host.
Available tables: N/A. All fields on the created comment are returned.
Output format: identical to /comments.
Commit Statuses
/api/v2.0/commits
List all commit statuses.

Available tables: commit_statuses. Output format:

{
    "items": [
        {
            "id": 3689,
            "commit_sha": "cb94d4592f0a0085302ad2dbed1b4aaa5db85d09",
            "status": "success"
        }
    ],
    "has_more": true
}
Debug
/api/v2.0/debug
Return debugging information for the API.

No database queries are performed by this route; no tables are available.
Not really intended for API consumer use, more for API developers.
Output format:

{
    "params": {
        "key": "abcdef012345",
        "per_page": "1"
    },
    "ts": "2017-12-18T00:46:14.812+00:00",
    "filters": {
        "announcements": "IJIHMOFFGGKIOKOGFJHMHHLOMIJFNGLLOHKMGIFKOMKLIILOGHLNNMJHJ",
        "apps": "MJMFOGKMLGMHGHFNGNJJOLOJGMKMIKMMKMHMFGJGIKIHHFLJKFLFLFN",
        "commits": "GFHIFKGGJLGIGLIHFJHMJHKMOINHOFGIONGGIMKOGKHMNFFNIH",
        "deletions": "MOOHKNMFMOGKIIMKIIIOHLJFGJHNOGMGMHMLIMJIINGFOJJ",
        "tags": "GHJNNJGMIGGGMMGJNOKOHLFFFHHIHLNIFNHJJIIJOFIHOL",
        "feedbacks": "HJKLKLLJLIHMKLINOKKJIJMOIOLKOMGJHGFMHGJIGKKH",
        "posts": "HKOMIKHOJJOHKLINJNOHMHMHKFGHJN",
        "reasons": "HOKGJMOFKGMOIKHNHKNKLFF",
        "smokeys": "ILMLMLLNNIHNHOJJ",
        "domains": "INJNHOFLOMHGL",
        "users": "JIKH"
    }
}
/api/v2.0/debug/filter
Decode a filter back to a list of fields.

No database queries are performed by this route; no tables are available.
Pass a filter as the filter parameter to receive a list of fields the filter contains.
Output format:

{
    "fields": [
        "posts.id",
        "posts.title",
        "posts.link",
        "posts.site_id",
        "posts.user_link",
        "posts.username",
        "posts.user_reputation"
    ]
}
Deletion logs
/api/v2.0/deletions
List all deletion logs.

Available tables: deletion_logs.
Output format:

{
    "items": [
        {
            "id": 79044,
            "post_id": 78091,
            "is_deleted": true
        }
    ],
    "has_more": true
}
/api/v2.0/deletions/post/:id
List deletion logs on the post specified.

Available tables: deletion_logs.
Output format: identical to /deletions.
/api/v2.0/deletions/post/:id
[W] Add a deletion log to a post.

Write route. Requires a POST request, trusted key, and valid write token.
Available tables: N/A. All fields on the created deletion log are returned.
Parameters: is_deleted (Boolean, required), uncertainty (Integer, seconds uncertainty, optional), timestamp (DateTime, deletion timestamp, optional)
Output format:

{
    "items": [
        {
            "id": 106575,
            "post_id": 100000,
            "is_deleted": true,
            "created_at": "2021-01-01T00:00:00.000Z",
            "updated_at": "2018-02-15T21:12:02.000Z",
            "api_key_id": 1,
            "uncertainty": 0
        }
    ],
    "has_more": false
}
Tags
/api/v2.0/tags
List all tags.

Available tables: domain_tags.
Output format:

{
    "items": [
        {
            "id": 16,
            "name": "blargle",
            "description": null
        }
    ],
    "has_more": true
}
/api/v2.0/tags/name/:name
List tags specified by their name.

Available tables: domain_tags.
Output format: identical to /tags.
/api/v2.0/tags/:id/domains
List the domains that a specific tag is used on.

Available tables: spam_domains.
Output format:

{
    "items": [
        {
            "id": 12935,
            "domain": "infinitemlmsoftware.com",
            "whois": null
        }
    ],
    "has_more": false
}
Feedbacks
/api/v2.0/feedbacks
List all feedbacks

Available tables: feedbacks.
Output format:

{
    "items": [
        {
            "id": 141289,
            "feedback_type": "fp-",
            "post_id": 78000,
            "user_id": 7
        }
    ],
    "has_more": true
}
/api/v2.0/feedbacks/post/:id
List all feedbacks on the post specified.

Available tables: feedbacks.
Output format: identical to /feedbacks.
/api/v2.0/feedbacks/user/:id
List all feedbacks by the user specified.

Available tables: feedbacks.
Output format: identical to /feedbacks.
/api/v2.0/feedbacks/app/:id
List all feedbacks created by the app specified.

Available tables: feedbacks.
Output format: identical to /feedbacks.
/api/v2.0/feedbacks/post/:id/create
[W] Create a feedback on the post specified.

Available tables: feedbacks. Returns all feedbacks on the post.
Write route. Requires POST request, valid write token, and parameters: type (feedback type, i.e. tpu-).
Output format: identical to /feedback.
Moderator Sites
/api/v2.0/mods
List all ModeratorSites.

Available tables: moderator_sites.
Output format:

{
    "items": [
        {
            "id": 970,
            "user_id": 5,
            "site_id": 1
        }
    ],
    "has_more": true
}
/api/v2.0/mods/user/:id
List all ModeratorSites for the specified user.

Available tables: moderator_sites.
Output format: identical to /mods.
Posts
/api/v2.0/posts
List all posts.

Available tables: posts.
Output format:

{
    "items": [
        {
            "id": 78099,
            "title": "test",
            "link": "//stackoverflow.com/a/3498236",
            "site_id": 1,
            "user_link": "//stackoverflow.com/u/3160466",
            "username": "ArtOfCode",
            "user_reputation": 3478
        }
    ],
    "has_more": true
}
/api/v2.0/posts/between
List posts within a specified date range.

Requires params: from (range start date) and to (range end date). Both are in ISO 8601 format - 1970-01-01T00:00:00.000000Z.
Available tables: posts.
Output format: identical to /posts.
/api/v2.0/posts/site
List posts on a specific site.

Requires params: site (site domain name).
Available tables: posts.
Output format: identical to /posts.
/api/v2.0/posts/urls
List posts specified by their URLs.

Requires params: urls (a comma separated list of URLs).
URLs are of the format //stackoverflow.com/a/12345 (for answers) or //stackoverflow.com/questions/12345 (for questions).
Available tables: posts.
Output format: identical to /posts.
/api/v2.0/posts/feedback
List posts by feedback types.

Requires params: type (feedback type).
Available tables: posts.
Output format: identical to /posts.
/api/v2.0/posts/undeleted
List posts that have not yet been deleted.

Looks for the absence of a DeletionLog record with is_deleted: true on the post - may not be 100% accurate; use the SE API if that's what you need.
Available tables: posts.
Output format: identical to /posts.
/api/v2.0/posts/uid/:api_param/:native_id
Get a post by its API site parameter and SE-native ID.

Finds posts on the site specified by :api_param with the post ID specified in :native_id, and returns them.
Available tables: posts.
Output format: identical to /posts.
/api/v2.0/posts/:ids
List posts by their IDs

ids is a comma separated list of post IDs to return.
Available tables: posts.
Output format: identical to /posts.
/api/v2.0/posts/:id/reasons
List the reasons a post was caught by.

Available tables: reasons.
Output format:

{
    "items": [
        {
            "id": 106,
            "reason_name": "Repeated url at end of long post",
            "weight": 99
        }
    ],
    "has_more": true
}
/api/v2.0/posts/:id/domains
List the domain names contained in a post.

Available tables: spam_domains.
Output format:

{
    "items": [
        {
            "id": 3993,
            "domain": "www.drhelpnutrition.org",
            "whois": null
        }
    ],
    "has_more": false
}
/api/v2.0/posts/:id/flags
Get details of what automatic and manual flags have been cast on a post.

Available tables: N/A. This route provides a specific, unfilterable subset of information.
Output format:

{
    "items": [
        {
            "id": 78000,
            "autoflagged": {
                "flagged": true,
                "users": [
                    {
                        "id": 14,
                        "username": "ProgramFOX",
                        "stackexchange_chat_id": 123456,
                        "stackoverflow_chat_id": 123456,
                        "meta_chat_id": 123456
                    },
                    {
                        "id": 42,
                        "username": "QPaysTaxes",
                        "stackexchange_chat_id": 123456,
                        "stackoverflow_chat_id": 123456,
                        "meta_chat_id": 123456
                    },
                    {
                        "id": 226,
                        "username": "guiniveretoo",
                        "stackexchange_chat_id": 123456,
                        "stackoverflow_chat_id": 123456,
                        "meta_chat_id": 123456
                    }
                ]
            },
            "manual_flags": {
                "users": [
                    {
                        "id": 7,
                        "username": "ArtOfCode",
                        "stackexchange_chat_id": 123456,
                        "stackoverflow_chat_id": 123456,
                        "meta_chat_id": 123456
                    }
                ]
            }
        }
    ],
    "has_more": false
}
/api/v2.0/posts/report
[W] Report a post.

Write route. Requires a POST request, valid write token, and parameters: url (the post URL to report).
Available tables: N/A. No database information is returned from this request.
All requests to this route will be met with a 202 Accepted status; metasmoke does not know the status of reports as it just forwards them to Smokey.
Output format:

{
    "status": "Accepted"
}
/api/v2.0/posts/:id/flag
[W] Cast a flag on a post.

Write route. Requires a POST request and valid write token.
Available tables: N/A. No database information is returned from this request.
backoff will only be set on successful requests. message will only be set on failed requests.
Specify the flag_type param to choose your flag type: either spam (default) or abusive for an R/A flag.
Output format:

{
    "status": "success|failed",
    "backoff": "10",
    "message": "failure reason"
}
/api/v2.0/posts/search{.:format}
Get an RSS or Atom feed of posts matching certain criteria.

format may be either rss or atom, e.g. /api/v2.0/posts/search.rss.
Filters are not available on this route.
Output format for RSS and Atom feeds is consistent with RSS and Atom standards, respectively.
Reasons
/api/v2.0/reasons
List all reasons.

Available tables: reasons.
Output format:

{
    "items": [
        {
            "id": 134,
            "reason_name": "Pattern-matching email in body",
            "weight": 0
        }
    ],
    "has_more": true
}
/api/v2.0/reasons/:ids
List reasons specified by their IDs.

Available tables: reasons.
Output format: identical to /reasons.
/api/v2.0/reasons/:id/posts
List posts caught by a specific reason.

Available tables: posts.
Output format:

{
    "items": [
        {
            "id": 78099,
            "title": "test",
            "link": "//stackoverflow.com/a/3498236",
            "site_id": 1,
            "user_link": "//stackoverflow.com/u/3160466",
            "username": "ArtOfCode",
            "user_reputation": 3478
        }
    ],
    "has_more": true
}
Sites
/api/v2.0/sites
List all sites

Available tables: sites.
Output format:

{
    "items": [
        {
            "id": 1,
            "site_name": "Stack Overflow",
            "site_url": "https://stackoverflow.com"
        }
    ],
    "has_more": true
}
SmokeDetectors
/api/v2.0/smokeys
List all SmokeDetector instances.

Available tables: smoke_detectors.
Output format:

{
    "items": [
        {
            "id": 17,
            "last_ping": "2017-07-24T00:47:50.000Z",
            "location": "The Call of Midnight",
            "user_id": 47,
            "status_color": "critical"
        }
    ],
    "has_more": true
}
Domains
/api/v2.0/domains
List all domains.

Available tables: spam_domains.
Output format:

{
    "items": [
        {
            "id": 12935,
            "domain": "infinitemlmsoftware.com",
            "whois": null
        }
    ],
    "has_more": true
}
/api/v2.0/domains/:id/posts
List all posts containing a specific domain.

Available tables: posts.
Output format:

{
    "items": [
        {
            "id": 77988,
            "title": "Google Webmaster Tools show the error in Manual Action for my web - https://infinitemlmsoftware.com/",
            "link": "//drupal.stackexchange.com/questions/242498",
            "site_id": 86,
            "user_link": "https://drupal.stackexchange.com/users/77863/isha",
            "username": "isha",
            "user_reputation": 1
        }
    ],
    "has_more": false
}
/api/v2.0/domains/:id/tags/add
[W] Add a tag to a specified domain.

Write route. Requires a POST request, valid write token, and params: tag (the name of the tag to add).
Available tables: domain_tags.
Output format:

{
    "items": [
        {
            "id": 16,
            "name": "blargle",
            "description": null
        }
    ],
    "has_more": true
}
Users
/api/v2.0/users
List all users.

Available tables: users.
Output format:

{
    "items": [
        {
            "id": 311,
            "username": "Art"
        }
    ],
    "has_more": true
}
/api/v2.0/users/with_role/:role
List all users with the specified role

Available tables: users.
Output format:

{
    "items": [
        {
            "id": 311,
            "username": "Art"
        }
    ],
    "has_more": true
}

metasmoke is made with <3 by the Charcoal Team and the other awesome contributors from Charcoal HQ.

Home

API Documentation (V1)

WebSocket API Documentation

Setting up an instance

FAQ: Search

Clone this wiki locally