The Feedback API is for getting/posting product feedback data.
| URL: | /api/v1/feedback/ |
|---|---|
| Method: | HTTP GET |
| Payload format: | No payload–everything is done in the querystring |
| Response: | JSON |
Doing a GET without any querystring arguments will return the most recent 1,000 publicly visible responses for all products.
Warning
This API endpoint is throttled. If you hit it too often, you’ll get throttled. You just need to wait a bit for the throttle to expire.
Note
This API endpoint is still in flux. The documentation is rudimentary at best. Amongst other things, it’s difficult to discover valid values for things.
If you’re using this API endpoint and have issues, please open a bug.
String. Comma-separated list of feedback response ids.
Example:
?id=1
?id=1,2,3,4
Note
If you specify this, all other filters will be ignored.
String. Text query.
Example:
?q=crash
Boolean. 0 or 1. Restricts results to either happy feedback or
sad feedback.
Example:
?happy=0
Strings. Comma separated list of platforms. For valid platforms, see https://input.mozilla.org/.
Examples:
?platforms=linux
?platforms=linux,os x
Strings. Comma separated list of locales. For valid locales, see https://input.mozilla.org/.
Examples:
?locales=en-US
?locales=en-US,es,es-BR
Strings. Comma separated list of products. For valid products, see https://input.mozilla.org/.
Examples:
?products=Firefox
?products=Firefox OS,Firefox
Strings. Comma separated list of versions for a specific product. For valid versions, see https://input.mozilla.org/.
You must specify a product in order to specify versions.
Examples:
?products=Firefox&versions=31.0
?products=Firefox&versions=31.0,32.0
Date in YYYY-MM-DD format. Specifies the start for the date range you’re querying for.
Example:
?date_start=2014-08-12
Date in YYYY-MM-DD format. Specifies the end for the date range you’re querying for.
Defaults to today.
Example:
?date_end=2014-08-12
String. 1d, 7d, 14d, etc. The number of days from
date_start or date_end.
Example:
# Shows the last 7 days ending today
?date_delta=7d
# Shows 14 days ending 2014-08-12
?date_end=2014-08-12&date_delta=14d
# Shows 22 days starting 2014-08-12
?date_start=2014-08-12&date_delta=22d
max
Integer. Defaults to 1,000. Maximum is 10,000. Minimum is 1. The maximum number of responses you want to get back.
Example:
# Retrieve at most 500 responses ?max=500 # Retrieve at most 10000 responses ?max=10000
Show all the happy responses for Firefox for the last 7 days for the English locale:
?happy=1&products=Firefox&locales=en-US&date_delta=7d
Show sad responses for Windows platforms for the last day:
?happy=0&platforms=Windows 7,Windows XP, Windows 8.1,Windows 8,Windows Vista,Windows NT&date_delta=1d
| URL: | /api/v1/feedback/ |
|---|---|
| Method: | HTTP POST |
| Payload format: | JSON—make sure to have Content-type: application/json
header |
You can test early stages of your code against our -stage server at:
https://input.allizom.org/
But you want to make sure you test against production at some point since that’s where the product you’re using will be set up. Production is:
https://input.mozilla.org/
^^^^^^^
Note
If you’re building automated testing, you can use our -prod server,
but include the word TEST at the beginning of the description.
Boolean. All feedback is either happy or sad. This denotes whether this feedback is happy (True) or sad (False).
Valid values: true, false
String. Max length: None (but 10,000 characters is probably a good cutoff). This is the feedback text.
Example: "OMG! I love Firefox!"
Note
The form this field is on should have some informational text stating that data in this field will be publicly available and that the user should not include personally identifyable information.
Example informational text:
The content of your feedback will be public, so please be sure
not to include any personal information.
String. Max length: 20. The name of the product the user is giving feedback on.
Examples:"Firefox for Android", "Firefox OS"
Note
This must be a valid product in the system. Before you start posting to Input, please talk to the User Advocacy folks or an Input admin to have your product added.
String. Max length: 30. The channel of the product the user is giving feedback on.
Examples: "stable", "beta"
String. Max length: 30. The version of the product the user is giving feedback on as a string.
Examples: "22b2", "1.1"
String. Max length: 30. The name of the operating system/platform the product is running on.
Examples: "OS X", "Windows 8", "Firefox OS",
"Android", "Linux"
String. Max length: 8. The locale the user is using.
Examples: "en-US", "fr", "de"
String. Max length: 30. The country of origin for the device.
Examples: "Peru", "Mexico"
Note
This is only relevant to Firefox OS phones.
String. Max length: 255. The manufacturer of the device the product is running on.
Examples: "Geeksphone", "Samsung"
String. Max length: 255. The model name of the device the product is running on.
Examples: "Peak", "Galaxy Tab 10.1"
String. Max length: 50. The category classification for this feedback response.
Examples: "ui", "performance", "bookmarks"
String. Max length: 200. If the feedback relates to a specific webpage, then the url is the url of the webpage it refers to.
Examples: "https://facebook.com/", "https://google.com/"
String. The email address of the user. This allows us to contact the user at some later point to respond to the user’s feedback or ask for more information.
Example: "joe@example.com"
Note
The form this field is in should state that email addresses will not be publicly available.
Example informational text:
While your feedback will be publicly visible, email addresses
are kept private. We understand your privacy is important.
String. Max length: 255. The user agent of the client if applicable. For example if the user is using a Firefox OS device, this would be the user agent of the browser used to send feedback.
Example: 'Mozilla/5.0 (Mobile; rv:18.0) Gecko/18.0 Firefox/18.0'
String. Max length: 100. If this response was initiated by a blog post, wiki page, search, newsletter, tweet or something like that, this is the source that initiated the response. It has the same semantics as the utm_source querystring parameter:
https://support.google.com/analytics/answer/1033867
Example: 'Hacks blog'
Note
Don’t set the source if the user is leaving feedback of their own accord. Only set the source if you have prompted or asked the user to leave feedback.
String. Max length: 100. If this response was initiated by a marketing campaign, this is the name of the campaign. It has the same semantics as the utm_campaign querystring parameter:
https://support.google.com/analytics/answer/1033867
Example: 'show the firefox love post'
Note
Don’t set the campaign if the user is leaving feedback of their own accord. Only set the campaign if you have prompted or asked the user to leave feedback.
You can provide additional context in the form of key/value pairs by adding additional data to the JSON object.
Any fields that aren’t part of the required or optional fields list will get thrown into a JSON object and dumped in the feedback response context.
For example, if the product were the Firefox devtools and you want feedback responses to include the theme (dark or light) that the user was using, you could add this to the JSON object:
{
"happy": true,
"description": "devtools are the best!",
"product": "Devtools",
"theme": "dark"
}
That last key will get added to the feedback response context.
Note
Obviously, don’t use a key that’s already the name of a field. Also, since this is not future proof, you might want to prepend a unique string to any keys you add.
Note
It’s important you don’t add ids or data that allows you to correlate feedback responses to things in other data sets. That violates our privacy policy.
$ curl -v -XPOST 'https://input.allizom.org/api/v1/feedback' \
-H 'Accept: application/json; indent=4' \
-H 'Content-type: application/json' \
-d '
{
"happy": true,
"description": "Posting by api!",
"product": "Firefox"
}'
After posting feedback, you’ll get one of several responses:
Feedback has errors. Details will be in the response body.
Possibilities include: