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.
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/api/keys/mine.
For write authentication, the same flow applies as for v1:
https://metasmoke.erwaysoftware.com/oauth/request?key=YOUR_KEY_HERE
.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 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.
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:
|
/api/v2.0/announcements/active | List active (non-expired) announcements.Available tables: |
/api/v2.0/announcements/expired | List expired announcements.Available tables: |
/api/v2.0/announcements/create | [W] Create an announcement.Available tables: N/A. All fields are returned. Filter is ignored.
|
Apps | |
/api/v2.0/apps | List all apps.Available tables:
|
Comments | |
/api/v2.0/comments | List all comments.Available tables:
|
/api/v2.0/comments/post/:id | List all comments on a specified post.Available tables: |
/api/v2.0/comments/post/:id | [W] [Smokey] Add an automatic comment to a post.This route is for use by SmokeDetector instances only. |
Commit Statuses | |
/api/v2.0/commits | List all commit statuses.Available tables:
|
Debug | |
/api/v2.0/debug | Return debugging information for the API.No database queries are performed by this route; no tables are available.
|
/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.
|
Deletion logs | |
/api/v2.0/deletions | List all deletion logs.Available tables:
|
/api/v2.0/deletions/post/:id | List deletion logs on the post specified.Available tables: |
/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.
|
Tags | |
/api/v2.0/tags | List all tags.Available tables:
|
/api/v2.0/tags/name/:name | List tags specified by their name.Available tables: |
/api/v2.0/tags/:id/domains | List the domains that a specific tag is used on.Available tables:
|
Feedbacks | |
/api/v2.0/feedbacks | List all feedbacksAvailable tables:
|
/api/v2.0/feedbacks/post/:id | List all feedbacks on the post specified.Available tables: |
/api/v2.0/feedbacks/user/:id | List all feedbacks by the user specified.Available tables: |
/api/v2.0/feedbacks/app/:id | List all feedbacks created by the app specified.Available tables: |
/api/v2.0/feedbacks/post/:id/create | [W] Create a feedback on the post specified.Available tables: |
Moderator Sites | |
/api/v2.0/mods | List all ModeratorSites.Available tables:
|
/api/v2.0/mods/user/:id | List all ModeratorSites for the specified user.Available tables: |
Posts | |
/api/v2.0/posts | List all posts.Available tables:
|
/api/v2.0/posts/between | List posts within a specified date range.Requires params: |
/api/v2.0/posts/site | List posts on a specific site.Requires params: |
/api/v2.0/posts/urls | List posts specified by their URLs.Requires params: |
/api/v2.0/posts/feedback | List posts by feedback types.Requires params: |
/api/v2.0/posts/undeleted | List posts that have not yet been deleted.Looks for the absence of a DeletionLog record with |
/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/v2.0/posts/:ids | List posts by their IDs
|
/api/v2.0/posts/:id/reasons | List the reasons a post was caught by.Available tables:
|
/api/v2.0/posts/:id/domains | List the domain names contained in a post.Available tables:
|
/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.
|
/api/v2.0/posts/report | [W] Report a post.Write route. Requires a POST request, valid write token, and parameters:
|
/api/v2.0/posts/:id/flag | [W] Cast a spam flag on a post.Write route. Requires a POST request and valid write token.
|
/api/v2.0/posts/search{.:format} | Get an RSS or Atom feed of posts matching certain criteria.
|
Reasons | |
/api/v2.0/reasons | List all reasons.Available tables:
|
/api/v2.0/reasons/:ids | List reasons specified by their IDs.Available tables: |
/api/v2.0/reasons/:id/posts | List posts caught by a specific reason.Available tables:
|
Sites | |
/api/v2.0/sites | List all sitesAvailable tables:
|
SmokeDetectors | |
/api/v2.0/smokeys | List all SmokeDetector instances.Available tables:
|
Domains | |
/api/v2.0/domains | List all domains.Available tables:
|
/api/v2.0/domains/:id/posts | List all posts containing a specific domain.Available tables:
|
/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:
|
Users | |
/api/v2.0/users | List all users.Available tables:
|
/api/v2.0/users/with_role/:role | List all users with the specified roleAvailable tables:
|