API Documentation (V1)

Metasmoke offers a JSON API to access data about posts, reasons, and feedback. This is the documentation for said API.

If you’re looking for the WebSocket API, go here.

Getting Started

To get started, you’ll need an API key. No application can use the API without a key - you’ll get a 403 response. To get a key, ping a metasmoke admin in chat - they’ll be able to register one for you. Have a name in mind for your app - a name is necessary to register a key. You can edit it later, so it doesn’t have to be final. Also make sure that you have an active metasmoke account - this allows the registering admin to tie the key to your account, giving you control of your app.

Once you have your key, you should include it as the key query string parameter on all requests to the API.

Filters

The metasmoke API supports parameter-based filters (like the Stack Exchange API) so that you can filter a response down to only the fields you want.

To create a filter, visit metasmoke.erwaysoftware.com/api/filters and select the fields you want in the response. Only select the fields you need. Selecting fields from unrelated tables may break things.

N.B.: You can calculate filters yourself if you really want to, but you should have a thorough understanding of how to do so first. Ask ArtOfCode if you’re unsure.

Once you’ve got your filter, include it as the filter parameter on requests to the API that use it.

You may sometimes need to pass a blank filter (by appending ?filter= to the the URL) for all fields to be displayed.

Results

You can use the per_page query string parameter to adjust how many results you get, up to a maximum of 100.

The has_more field in the response indicates if there are more results available than have been returned in this result set; use the page query string parameter to get the next page of results. ?page=1 will return the first page; ?page=2 the second, and so on.

Write Methods

Write methods additionally require you to go through OAuth to get hold of a write token, which can be used to authorize the write request. You should follow this flow:

• Send your user to https://metasmoke.erwaysoftware.com/oauth/request?key=YOUR_KEY_HERE
• If the user authorizes your app, they’ll be given a code to provide you. Ask them to enter that code, then:
• Send an 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.

Write tokens do not expire and can be used to authorize as many requests as you need. If you get a 401 Unauthorized response when you included a write token, that token has likely been revoked by an administrator or by the user, and you need to go through OAuth again.

API Read Routes

• Domain Tags: /api/domains/:id/tags
• Post Domains: /api/post/:id/domains
• Post Feedback: /api/post/:id/feedback
• Post Reasons: /api/post/:id/reasons
• Posts by Date Range: /api/posts/between
• Posts by Feedback: /api/posts/feedback
• Posts by ID: /api/posts/:ids
• Posts by Site: /api/posts/site
• Posts by URLs: /api/posts/url
• Posts caught by reason: /api/reason/:id/posts
• Reasons by ID: /api/reasons/:ids
• Search Posts: /api/posts/search
• Undeleted Posts: /api/posts/undeleted
• Users: /api/users
• Valid Feedback Types: /api/post/:id/valid_feedback
• Smoke Detectors: /api/smoke_detectors
• Spam Last Week: /api/stats/last_week
• Detailed Time to Deletion: api/stats/detailed_ttd

API Write Routes

• Add Domain Tag: POST /api/w/domains/:id/add_tag
• Create Feedback: POST /api/w/post/:id/feedback
• Report Post: POST /api/w/post/report