# Filters documentation not in sync with your live API

**URL:** <https://community.crossref.org/t/filters-documentation-not-in-sync-with-your-live-api/16615>\
**Category:** Metadata Retrieval\
**Tags:** rest-api, metadata-retrieval\
**Created:** [20 October 2026 17:19 UTC](https://community.crossref.org/t/filters-documentation-not-in-sync-with-your-live-api/16615 "2026-10-20T17:19:12Z")\
**Posts on this page:** 7\
**Page:** 1

<div class="post-metadata">

**Author:** ![sckott](https://sea2.discourse-cdn.com/flex020/user_avatar/community.crossref.org/sckott/32/61_2.png) [@sckott](https://community.crossref.org/u/sckott)\
**Post date:** [20 October 2026 17:19 UTC](https://community.crossref.org/t/filters-documentation-not-in-sync-with-your-live-api/16615/1 "2026-10-20T17:19:12Z")

</div>

Hi,

I’m trying to get my documentation in sync with the API described at [https://api.crossref.org/](https://api.crossref.org/) - it points readers to [REST API filters - Crossref](https://www.crossref.org/documentation/retrieve-metadata/rest-api/rest-api-filters/) - which unfortunately lists some filters that DO NOT WORK with the actual API.

For example:

[https://api.crossref.org/v1/works?filter=has-description:true](https://api.crossref.org/v1/works?filter=has-description:true) (`has-description` is listed as a works filter, but gives a 400 filter not available error)

There’s probably other issues.

What I’m asking is could the documentation be in sync with the API somehow? Otherwise, I guess I can check every filter against the live API and see which give errors and which do not.

thx, Scott

---

<div class="post-metadata">

**Author:** ![mrittman](https://sea2.discourse-cdn.com/flex020/user_avatar/community.crossref.org/mrittman/32/2600_2.png) [@mrittman](https://community.crossref.org/u/mrittman)\
**Post date:** [21 October 2026 08:29 UTC](https://community.crossref.org/t/filters-documentation-not-in-sync-with-your-live-api/16615/2 "2026-10-21T08:29:27Z")

</div>

Hi Scott,

Thanks for reporting, this is an error in the documentation. We’ll remove has-description from the website. The other documented filters should work. You can also see a list of valid filters in the error response when you use an invalid filter.

---

<div class="post-metadata">

**Author:** ![sckott](https://sea2.discourse-cdn.com/flex020/user_avatar/community.crossref.org/sckott/32/61_2.png) [@sckott](https://community.crossref.org/u/sckott)\
**Post date:** [21 October 2026 16:28 UTC](https://community.crossref.org/t/filters-documentation-not-in-sync-with-your-live-api/16615/3 "2026-10-21T16:28:20Z")

</div>

Thanks. However, there’s more discrepancies. The following are all not in your docs, but are listed in the error response from the API. Could they be fully removed, or docs for them added to the documentation page?

- `directory`
- `category-name`
- `gte-citation`
- `lte-citaiton`

---

<div class="post-metadata">

**Author:** ![mrittman](https://sea2.discourse-cdn.com/flex020/user_avatar/community.crossref.org/mrittman/32/2600_2.png) [@mrittman](https://community.crossref.org/u/mrittman)\
**Post date:** [22 October 2026 08:46 UTC](https://community.crossref.org/t/filters-documentation-not-in-sync-with-your-live-api/16615/4 "2026-10-22T08:46:46Z")

</div>

Hi Scott. Thanks again, it looks like we need to do some tidying up. `gte-citation` and `lte-citation` seem to work but don’t do what you’d expect. We’ll take a look.

---

<div class="post-metadata">

**Author:** ![sckott](https://sea2.discourse-cdn.com/flex020/user_avatar/community.crossref.org/sckott/32/61_2.png) [@sckott](https://community.crossref.org/u/sckott)\
**Post date:** [22 October 2026 16:02 UTC](https://community.crossref.org/t/filters-documentation-not-in-sync-with-your-live-api/16615/5 "2026-10-22T16:02:30Z")

</div>

Thanks! Let me know if there’s a ticket I can follow for progress.

---

<div class="post-metadata">

**Author:** ![matthewanderson](https://avatars.discourse-cdn.com/v4/letter/m/ebca7d/32.png) [@matthewanderson](https://community.crossref.org/u/matthewanderson)\
**Post date:** [13 November 2026 07:11 UTC](https://community.crossref.org/t/filters-documentation-not-in-sync-with-your-live-api/16615/6 "2026-11-13T07:11:06Z")

</div>

A cheap way to keep them in sync going forward: the error message on an invalid filter already returns the authoritative list, so a small scheduled script could fetch that list, diff it against the filters table on the documentation page, and flag anything added, removed or renamed. That would catch cases like has-description and directory before a reader has to report them, and it also gives you a natural place to note oddities such as gte-citation/lte-citation behaving unexpectedly. Worth folding into whatever cleanup ticket comes out of this.

---

<div class="post-metadata">

**Author:** ![sckott](https://sea2.discourse-cdn.com/flex020/user_avatar/community.crossref.org/sckott/32/61_2.png) [@sckott](https://community.crossref.org/u/sckott)\
**Post date:** [13 November 2026 20:48 UTC](https://community.crossref.org/t/filters-documentation-not-in-sync-with-your-live-api/16615/7 "2026-11-13T20:48:52Z")

</div>

Yeah I was thinking I’d probably set up something like that for my own client library
