Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/TheOutdoorProgrammer/crate/llms.txt

Use this file to discover all available pages before exploring further.

Crate maintains two distinct lists of blocked sources to protect download quality and avoid wasting bandwidth on problem users. Understanding the difference between them helps you manage your source health effectively. Blacklist entries are permanent, per-user per-file blocks. A specific filename from a specific username is blacklisted whenever a transfer errors out or when you manually reject an owned track. Blacklisted entries are never re-tried by the auto-downloader or surfaced as the best pick in manual search (though they are still shown dimmed so you can see them). Cooldowns (shadow bans) are temporary, per-user blocks that expire automatically. A user is placed on cooldown when they go offline mid-transfer or when a queued download stalls for too long waiting for a slot. During a cooldown, all files from that user are skipped across every download in the queue — not just the one that triggered the ban. The cooldown duration defaults to 60 minutes and is configurable via the shadow_ban_duration setting.
Blacklist = one specific file from one specific user, permanent until you remove it. Cooldown = all files from one user, temporary (expires automatically after the configured duration). A user can appear in both lists simultaneously — for example, if a transfer errors out (file blacklisted) and the user also went offline at some point (user cooled down).
Both lists are viewable and manageable in the Crate UI under Settings → Blocked Sources. Use the API when you want to script bulk cleanup or integrate blocked-source management into a larger workflow.

​
GET /api/blacklist/

Returns all permanent blacklist entries. Each entry records the specific username and filename combination that was blocked, along with the reason it was added. Response — array of BlacklistEntry
​
id
integer
The entry’s internal ID. Use this to delete individual entries.
​
username
string
The slskd username whose file was blacklisted.
​
filename
string
The full remote file path on the user’s machine that is blocked (e.g. music/Radiohead/OK Computer/06 - Karma Police.flac).
​
reason
string
Why the entry was created — typically "transfer Errored", "track rejected", or a similar description of the triggering event.
​
created_at
string
RFC 3339 timestamp when the entry was created.
curl http://localhost:6969/api/blacklist/
Example response 
[
  {
    "id": 1,
    "username": "vinylhead99",
    "filename": "music/Radiohead/OK Computer/06 - Karma Police.flac",
    "reason": "transfer Errored",
    "created_at": "2024-11-01T14:32:00Z"
  },
  {
    "id": 2,
    "username": "losslessonly",
    "filename": "mp3collection/radiohead/karma_police.mp3",
    "reason": "track rejected",
    "created_at": "2024-11-03T09:15:00Z"
  }
]

​
DELETE /api/blacklist/{id}

Removes a single blacklist entry. Once removed, the username+filename pair will be eligible for selection again by the auto-downloader and will no longer appear dimmed in manual search results.
​
id
integer
required
The blacklist entry ID, as returned by GET /api/blacklist/.
Returns 204 No Content on success. 
curl -X DELETE http://localhost:6969/api/blacklist/1

​
DELETE /api/blacklist/

Removes all blacklist entries at once. After this call, no username+filename pairs are permanently blocked and every previously-blacklisted file becomes a candidate for download again.
Clearing the entire blacklist permanently removes all previously blocked file sources. Files that previously caused transfer errors or were manually rejected will be attempted again. This cannot be undone.
Returns 204 No Content on success. 
curl -X DELETE http://localhost:6969/api/blacklist/

​
GET /api/cooldowns/

Returns all active user cooldowns. Only non-expired cooldowns are returned — the database query filters to entries whose expires_at is in the future. Expired cooldowns are cleaned up automatically and will not appear in this list. Response — array of UserCooldown
​
id
integer
The cooldown entry’s internal ID.
​
username
string
The slskd username that is currently blocked.
​
reason
string
Why the cooldown was applied — typically "went offline mid-transfer" or "queued download stalled".
​
expires_at
string
RFC 3339 timestamp when the cooldown will automatically expire and the user will become available again.
​
created_at
string
RFC 3339 timestamp when the cooldown was applied.
curl http://localhost:6969/api/cooldowns/
Example response 
[
  {
    "id": 3,
    "username": "spottyseeder",
    "reason": "went offline mid-transfer",
    "expires_at": "2024-11-05T11:00:00Z",
    "created_at": "2024-11-05T10:00:00Z"
  },
  {
    "id": 4,
    "username": "slowqueue42",
    "reason": "queued download stalled",
    "expires_at": "2024-11-05T11:30:00Z",
    "created_at": "2024-11-05T10:30:00Z"
  }
]

​
DELETE /api/cooldowns/{id}

Lifts the shadow ban for a specific cooldown entry immediately, before it would have expired naturally. Use this when you know a user has come back online and you want Crate to try them again right away without waiting for the cooldown window to pass.
​
id
integer
required
The cooldown entry ID, as returned by GET /api/cooldowns/.
Returns 204 No Content on success. 
curl -X DELETE http://localhost:6969/api/cooldowns/3

​
DELETE /api/cooldowns/

Clears all active cooldown entries at once, immediately lifting every current shadow ban. All previously-cooled-down users become available for download selection again on the next scheduler tick. Returns 204 No Content on success. 
curl -X DELETE http://localhost:6969/api/cooldowns/

Build docs developers (and LLMs) love

Get started for freeTalk to us