I use the Charcoal FIRE userscript to red-flag posts. Today I found this SuperUser question (possibly 10k by now since it's spam) and I spam flagged both the question and answer. The question I flagged manually.

Shortly thereafter the question was added to Charcoal and I used FIRE to confirm it was spam. Previously, this would result in FIRE letting me know I had already flagged it, but the flag API call went through and retracted my previous flag. This wasn't expected behavior. I mod flagged it for removal, but the API shouldn't merely retract the flag on a second request.

Is this behavior intended, or is this a bug?

  • 3
    I had a slightly different experience with the same question. I visited the Q&A page and flagged both the seed question and answer as spam using the Charcoal FDSC userscript. At some point, my flag on the question was reportedly self-removed, although I (to my knowledge) did not perform such an action. Commented Jul 14, 2021 at 15:46
  • 1
    Note: There have been no recent code changes wrt. flagging for FIRE or metasmoke. In other words, the API requests which would have been send would have been exactly the same as have been used over the last few years.
    – Makyen
    Commented Jul 15, 2021 at 1:40

2 Answers 2


This was a bug introduced in the API 2.3 Release as part of allowing retracting flags from the API. If you pass a flag id through flag_option.id to /flags/add that is possible to retract, it will retract it instead of throwing an error.

However, we accidentally added this retraction feature to earlier versions of the API. API consumers like the Charcoal user script that depended on getting an error when trying to add a flag the second time were now accidentally retracting flags. We've fixed this bug so that calls on the API before 2.3 will stop retracting flags and will instead continue to get an error response as previously expected.

With this new retraction feature, there was also an instance where certain API calls could accidentally retract other users flags, marking them as self-cleared. This could have also been the source of some flags getting mistakenly retracted. We also fixed this bug and you should no longer see your flags cleared like this.

I'm not personally familiar with the Charcoal userscripts, but if it gets upgraded to using v2.3 of the API, it will need to handle this new retracting feature when adding a flag for the second time. Right now, this functionality isn't documented in the API docs but is mentioned in this post. We'll work on getting this previously undefined behavior documented better in the change log and /flags/add endpoints for v2.3. It's also possible that how retractions are done through the API may move away from the /flags/add endpoint in a future release, but we're still figuring it out internally. We'll make sure to communicate any breaking changes in future release notes.

  • 3
    Not sure I understand this. In order to retract a flag one must use the "add" endpoint? To know if one has already added a flag (which would make sense to do first if one is trying to retract it, and there's only one endpoint) one needs to call the 2.2 version and try to add it and upon an error then call the 2.3 version to retract?... Which risks one actually adding a flag.. in case none was already raised. Please tell me this isn't how it works. Commented Jul 16, 2021 at 19:00
  • 2
    Thanks for fixing this. Thank you also for keeping us updated if you make any breaking changes. Doing so certainly helps.
    – Makyen
    Commented Jul 16, 2021 at 19:17
  • @Unconsidered That's not how it works. In both 2.2 and 2.3 the first step in raising a flag is to GET [answers|questions]/{id}/flags/options to receive the available flagging options. In particular, you obtain an option_id for each type of flag, and if the user has already raised that type of flag is indicated in has_flagged. That option_id is then passed to POST [answers|questions]/{id}/flags/add as the action you want to take. The option_id is not guaranteed to be static long-term, so it's not something you can hard-code (i.e. you must make the GET each time).
    – Makyen
    Commented Jul 16, 2021 at 19:41
  • In the 2.2 API, the response to the GET to .../flags/options does not include option_id numbers for retractions (which are a different number than raising a flag). In the 2.2 API, the information you GET is always about raising flags. If you try to .../flags/add with the option_id provided by the 2.2 API for any flag you've already raised, except custom flags (which can be re-raised), you get an error.
    – Makyen
    Commented Jul 16, 2021 at 19:41
  • In the 2.3 API, if you've raised a flag, then the response to the GET contains for that type of flag an object which includes an option_id for retraction and the object contains a new property is_retraction: true. It will not contain an object indicating the option_id for raising a flag. If that is_retraction: true option_id is then sent to .../flags/add, then the existing flag is retracted. The object describing the flag option is functionally identical, except for the existence of the is_retraction: true.
    – Makyen
    Commented Jul 16, 2021 at 19:41
  • The issue was that the 2.2 API was supplying the same data for the GET to .../flags/options as was supplied for the 2.3 API and was performing retraction when the option_id for the retraction was passed to .../flags/add.
    – Makyen
    Commented Jul 16, 2021 at 19:42
  • Thus, when code written for the 2.2 API performed those calls, and didn't choose to not call .../flags/add when has_flagged was present, the flag was retracted. Many of the scripts/apps written for the 2.2 API ignore has_flagged, as it might be wrong/outdated, and obey the user's command to try to raise the flag, relying on getting an error from the .../flags/add if raising the flag is actually not possible. For the 2.3 API, the logic must change and pay attention to both/either is_retraction and/or has_flagged to indicate to the user what the script/app can perform.
    – Makyen
    Commented Jul 16, 2021 at 19:42
  • Note: I forgot to include flags on comments, so should have said: [answers|questions|comments]/{id}/flags/options and [answers|questions|comments]/{id}/flags/add as the endpoints. The documentation is in the SE API docs.
    – Makyen
    Commented Jul 16, 2021 at 20:01
  • 7
    @Makyen your analysis is spot on and provides better clarification than I could have in my post - thanks for taking the time to write that out! You're amazing 🙌
    – Kyle Pollard StaffMod
    Commented Jul 16, 2021 at 20:26

To follow up on Kyle's answer, I've updated the API docs to be clear about this change and its ramifications. The updated copy should be live today or tomorrow.

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .