Document collectibles spam filtering flags (#144)

Author: shaneauerbach

evm/collectibles.mdx

@@ -26,10 +26,10 @@ See the [Compute Units](/compute-units) page for detailed information.
 
 ## Spam Filtering
 
-By default, spam filtering for collectibles is enabled. Use `filter_spam=false` to disable it. You can omit the parameter or set `filter_spam=true` to keep spam filtering enabled.
+By default, spam filtering for collectibles is enabled. Use `filter_spam=false` to include spam collectibles in the response. You can omit the parameter or set `filter_spam=true` to keep spam filtering enabled.
 
-We provide spam scores to explain how a collectible is classified as spam or not.
-Spam scores are _off_ by default. Enable them with `show_spam_scores=true`.
+We provide spam scores to explain how a collectible is classified as spam or not. The `is_spam` field is always included in each entry. Spam scores are _off_ by default and require `show_spam_scores=true` to include `spam_score` and `explanations`.
+Setting `show_spam_scores=true` does not disable filtering; use `filter_spam=false` if you want spam entries (and their scores) returned.
 Scores are computed as a weighted average across signals.
 These include whether the collection has been flagged by external providers, trade volume since launch, and the number of unique buyers and sellers.
 See the table below for the full list.
@@ -41,10 +41,11 @@ See the table below for the full list.
 | `trade_volume` | This is the total number of trades since collection launch. Very low activity can indicate spam. Collections launched in the last 7 days are excluded from this signal. |
 | `unique_buyers` | This is the count of distinct buyers. Low buyer diversity can indicate inorganic activity. |
 | `unique_sellers` | This is the count of distinct sellers. Low seller diversity can indicate inorganic activity. |
-| `externally_flagged` | Whether the collection has been flagged as spam by third-party providers. `true` increases the spam likelihood. |
-| `ipfs_uri_present` | This indicates whether token metadata URIs use IPFS. Certain patterns can correlate with spam when combined with other signals. |
-| `suspicious_words` | Whether names, symbols, or URIs include suspicious terms commonly associated with scams. |
-| `url_shortener_in_uri` | This indicates whether metadata URIs use link shorteners. For example, Bitly links can obscure destinations. |
+| `externally_flagged` | Whether the collection has been flagged as spam by third-party providers (for example, Alchemy). `true` increases the spam likelihood. |
+| `uri_non_ipfs` | Whether metadata URIs are non-IPFS. Certain patterns can correlate with spam when combined with other signals. |
+| `suspicious_words` | Whether names or symbols include suspicious terms commonly associated with scams. |
+| `url_shortener` | Whether metadata URIs use link shorteners (for example, Bitly). |
+| `manual_classification` | Manual override for classification (`spam` or `not spam`). |
 
 </Accordion>
 

evm/openapi/collectibles.json

@@ -138,16 +138,18 @@
                     "unique_buyers",
                     "unique_sellers",
                     "externally_flagged",
-                    "ipfs_uri_present",
+                    "uri_non_ipfs",
                     "suspicious_words",
-                    "url_shortener_in_uri"
+                    "url_shortener",
+                    "manual_classification"
                   ]
                 },
                 "value": {
                   "description": "Observed value for the feature (type varies by feature).",
                   "oneOf": [
                     { "type": "integer", "format": "int32" },
-                    { "type": "boolean" }
+                    { "type": "boolean" },
+                    { "type": "string" }
                   ]
                 },
                 "feature_score": {
@@ -286,7 +288,7 @@
             "name": "filter_spam",
             "in": "query",
             "required": false,
-            "description": "When true, hide collectibles identified as spam. Set to false to return all collectibles, including potential spam. See the [Spam Filtering](##spam-filtering) section for more details.",
+            "description": "When true, hide collectibles identified as spam. Set to false to return all collectibles, including potential spam. See the [Spam Filtering](#spam-filtering) section for more details.",
             "schema": {
               "type": "boolean",
               "default": true
@@ -296,7 +298,7 @@
             "name": "show_spam_scores",
             "in": "query",
             "required": false,
-            "description": "When true, include spam scoring details including contributing signals to explain filtering decisions.",
+            "description": "When true, include spam scoring details (`spam_score` and `explanations`) to explain filtering decisions.",
             "schema": {
               "type": "boolean",
               "default": false