Tag APIs
Use these APIs to create, organize, and manage tags on dockets in our system.
Overview
Tags help you organize and share collections of cases. You can create public tags that others can view or you can create private tags for your own use. Tags can be described using markdown to create sharable collections with unique URLs.
This page focuses on the tags API itself. To learn more about tags generally and how to use them in the web interface, read the tags documentation.
Tags
Tags are collections you create to organize dockets. Each tag has a name, optional description, and can be made public or private.
Fields
name(required) — A unique slug for your tag (lowercase, no spaces)title(optional) — A human-friendly title of the tag for display on its pagedescription(optional) — Markdown description of the tagpublished(optional) — Boolean, whether the tag is public (default: false)view_count(read-only) — Number of times the tag page has been viewed
To learn more about this API, make an HTTP OPTIONS request:
curl -X OPTIONS \
--header 'Authorization: Token <your-token-here>' \
"https://www.courtlistener.com/api/rest/v4/tags/"
Learn more about filtering, sorting, and serialization by reviewing the query refinement documentation.
Create a Tag
Create a new tag with an HTTP POST request:
curl -X POST \
--data 'name=my-important-cases' \
--data 'title=My Important Cases' \
--data 'description=Cases I am tracking for work' \
--data 'published=false' \
--header 'Authorization: Token <your-token-here>' \
"https://www.courtlistener.com/api/rest/v4/tags/"
The response:
{
"id": 123,
"date_created": "2024-12-08T10:30:00.000000-08:00",
"date_modified": "2024-12-08T10:30:00.000000-08:00",
"user": 456,
"name": "my-important-cases",
"title": "My Important Cases",
"description": "Cases I am tracking for work",
"published": false,
"view_count": 0,
"dockets": []
}
Update a Tag
Update a tag with an HTTP PATCH request:
curl -X PATCH \
--data 'published=true' \
--header 'Authorization: Token <your-token-here>' \
"https://www.courtlistener.com/api/rest/v4/tags/123/"
List Your Tags
List all your tags with an HTTP GET request:
curl -X GET \
--header 'Authorization: Token <your-token-here>' \
"https://www.courtlistener.com/api/rest/v4/tags/"
Delete a Tag
Delete a tag with an HTTP DELETE request:
curl -X DELETE \
--header 'Authorization: Token <your-token-here>' \
"https://www.courtlistener.com/api/rest/v4/tags/123/"
Docket-Tags
It's not enough to create a tag as above. You also have to associate it with a case. Docket-Tags create this linkage between a tag you created and a docket you want tagged.
Fields
tag(required) — The ID of the tag.docket(required) — The ID of the docket to tag.
To learn more about this API, make an HTTP OPTIONS request:
curl -X OPTIONS \
--header 'Authorization: Token <your-token-here>' \
"https://www.courtlistener.com/api/rest/v4/docket-tags/"
Learn more about filtering, sorting, and serialization by reviewing the query refinement documentation.
Tag a Docket
Add a docket to a tag with an HTTP POST request. The following tags docket 456789 with tag 123:
curl -X POST \
--data 'tag=123' \
--data 'docket=456789' \
--header 'Authorization: Token <your-token-here>' \
"https://www.courtlistener.com/api/rest/v4/docket-tags/"
The response:
{
"id": 789,
"tag": 123,
"docket": 456789
}
List Tagged Dockets
To see all dockets tagged with a specific tag, filter by tag ID:
curl -X GET \
--header 'Authorization: Token <your-token-here>' \
"https://www.courtlistener.com/api/rest/v4/docket-tags/?tag=123"
Untag a Docket
To untag a docket, delete the Docket Tag object:
curl -X DELETE \
--header 'Authorization: Token <your-token-here>' \
"https://www.courtlistener.com/api/rest/v4/docket-tags/789/"
Related APIs
Tags are related to the Pray and Pay program, which allows you to request PACER documents for cases you're tracking. When using Pray and Pay, you can organize the cases you're monitoring using tags, making it easy to manage large collections of cases.
mike