diff --git a/changelogs/unreleased/docs-28814-clarify-artifacts-ref.yml b/changelogs/unreleased/docs-28814-clarify-artifacts-ref.yml
new file mode 100644
index 00000000000..3cdcff8caaf
--- /dev/null
+++ b/changelogs/unreleased/docs-28814-clarify-artifacts-ref.yml
@@ -0,0 +1,5 @@
+---
+title: Clarify artifact download via the API only accepts branch or tag name for ref
+merge_request:
+author:
+type: other
diff --git a/doc/api/jobs.md b/doc/api/jobs.md
index d60c7c12881..e7060e154f4 100644
--- a/doc/api/jobs.md
+++ b/doc/api/jobs.md
@@ -336,7 +336,7 @@ Parameters
 | Attribute   | Type    | Required | Description               |
 |-------------|---------|----------|-------------------------- |
 | `id`        | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user       |
-| `ref_name`  | string  | yes      | The ref from a repository |
+| `ref_name`  | string  | yes      | The ref from a repository (can only be branch or tag name, not HEAD or SHA) |
 | `job`       | string  | yes      | The name of the job       |
 
 Example request: