{ "openapi": "3.1.0", "info": { "title": "OpenXet", "description": "The HTTP API of an OpenXet server: the Xet CAS, the Hugging Face Hub API, Git smart HTTP, Git LFS and the file gateway. Every error is `{\"schema\":\"openxet.error.v1\",\"code\",\"message\",\"hint\"}`: `code` is stable, `hint` names the next action. Every answer carries `X-Request-Id`.", "license": { "name": "Apache-2.0", "identifier": "Apache-2.0" }, "version": "0.0.0" }, "paths": { "/api/agent-harnesses": { "get": { "tags": [ "hub" ], "summary": "Agent harnesses", "operationId": "get_api_agent_harnesses", "parameters": [], "responses": { "401": { "$ref": "#/components/responses/get_api_agent_harnesses_401" }, "403": { "$ref": "#/components/responses/get_api_agent_harnesses_403" }, "500": { "$ref": "#/components/responses/get_api_agent_harnesses_500" }, "501": { "$ref": "#/components/responses/get_api_agent_harnesses_501" }, "503": { "$ref": "#/components/responses/get_api_agent_harnesses_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/collections": { "get": { "tags": [ "hub" ], "summary": "Collections", "operationId": "get_api_collections", "parameters": [], "responses": { "401": { "$ref": "#/components/responses/get_api_agent_harnesses_401" }, "403": { "$ref": "#/components/responses/get_api_agent_harnesses_403" }, "500": { "$ref": "#/components/responses/get_api_agent_harnesses_500" }, "501": { "$ref": "#/components/responses/get_api_agent_harnesses_501" }, "503": { "$ref": "#/components/responses/get_api_agent_harnesses_503" } }, "security": [ { "accessToken": [] }, {} ] }, "post": { "tags": [ "hub" ], "summary": "Collections", "operationId": "post_api_collections", "parameters": [], "responses": { "401": { "$ref": "#/components/responses/get_api_agent_harnesses_401" }, "403": { "$ref": "#/components/responses/get_api_agent_harnesses_403" }, "500": { "$ref": "#/components/responses/get_api_agent_harnesses_500" }, "501": { "$ref": "#/components/responses/get_api_agent_harnesses_501" }, "503": { "$ref": "#/components/responses/get_api_agent_harnesses_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/collections/{rest}": { "get": { "tags": [ "hub" ], "summary": "A collection", "operationId": "get_api_collections_rest", "parameters": [ { "name": "rest", "in": "path", "description": "The rest of the path. It may hold `/`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_agent_harnesses_401" }, "403": { "$ref": "#/components/responses/get_api_agent_harnesses_403" }, "500": { "$ref": "#/components/responses/get_api_agent_harnesses_500" }, "501": { "$ref": "#/components/responses/get_api_agent_harnesses_501" }, "503": { "$ref": "#/components/responses/get_api_agent_harnesses_503" } }, "security": [ { "accessToken": [] }, {} ] }, "post": { "tags": [ "hub" ], "summary": "A collection", "operationId": "post_api_collections_rest", "parameters": [ { "name": "rest", "in": "path", "description": "The rest of the path. It may hold `/`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_agent_harnesses_401" }, "403": { "$ref": "#/components/responses/get_api_agent_harnesses_403" }, "500": { "$ref": "#/components/responses/get_api_agent_harnesses_500" }, "501": { "$ref": "#/components/responses/get_api_agent_harnesses_501" }, "503": { "$ref": "#/components/responses/get_api_agent_harnesses_503" } }, "security": [ { "accessToken": [] }, {} ] }, "delete": { "tags": [ "hub" ], "summary": "A collection", "operationId": "delete_api_collections_rest", "parameters": [ { "name": "rest", "in": "path", "description": "The rest of the path. It may hold `/`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_agent_harnesses_401" }, "403": { "$ref": "#/components/responses/get_api_agent_harnesses_403" }, "500": { "$ref": "#/components/responses/get_api_agent_harnesses_500" }, "501": { "$ref": "#/components/responses/get_api_agent_harnesses_501" }, "503": { "$ref": "#/components/responses/get_api_agent_harnesses_503" } }, "security": [ { "accessToken": [] }, {} ] }, "patch": { "tags": [ "hub" ], "summary": "A collection", "operationId": "patch_api_collections_rest", "parameters": [ { "name": "rest", "in": "path", "description": "The rest of the path. It may hold `/`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_agent_harnesses_401" }, "403": { "$ref": "#/components/responses/get_api_agent_harnesses_403" }, "500": { "$ref": "#/components/responses/get_api_agent_harnesses_500" }, "501": { "$ref": "#/components/responses/get_api_agent_harnesses_501" }, "503": { "$ref": "#/components/responses/get_api_agent_harnesses_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/datasets": { "get": { "tags": [ "hub" ], "summary": "List repositories", "description": "The repositories with the route's label that the caller may read, ordered by `{namespace}/{name}` ignoring case. `full`, `config`, `cardData` and `expand` are accepted and answered with what OpenXet has; any other filter or sort answers `501`.", "operationId": "get_api_datasets", "parameters": [ { "name": "author", "in": "query", "description": "Only this namespace's repositories.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "At most this many per page, and at most `hub.page_size`.", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "description": "Where the page starts, from the previous page's `Link`.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_200" }, "400": { "$ref": "#/components/responses/get_api_datasets_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/datasets-tags-by-type": { "get": { "tags": [ "hub" ], "summary": "Dataset card tags", "operationId": "get_api_datasets_tags_by_type", "parameters": [], "responses": { "401": { "$ref": "#/components/responses/get_api_agent_harnesses_401" }, "403": { "$ref": "#/components/responses/get_api_agent_harnesses_403" }, "500": { "$ref": "#/components/responses/get_api_agent_harnesses_500" }, "501": { "$ref": "#/components/responses/get_api_agent_harnesses_501" }, "503": { "$ref": "#/components/responses/get_api_agent_harnesses_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/datasets/{ns}/{name}": { "get": { "tags": [ "hub" ], "summary": "Repository info", "description": "The repository, with its files at the revision: `main` without one. A repository whose initial commit failed answers without `sha`.", "operationId": "get_api_datasets_ns_name", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "blobs", "in": "query", "description": "Each sibling with its `blobId`, `size` and, for an LFS file, `lfs`.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_200" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/datasets/{ns}/{name}/branch/{branch}": { "post": { "tags": [ "hub" ], "summary": "Create a branch", "description": "Creates `{branch}` at `startingPoint`, by default `main`'s tip. `create_branch(exist_ok=True)` treats the `409` as done.", "operationId": "post_api_datasets_ns_name_branch_branch", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "branch", "in": "path", "description": "A branch name.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Optional; an empty body starts at `main`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "startingPoint": { "type": "string", "description": "A revision." } } } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_200" }, "400": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_404" }, "408": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_408" }, "409": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_409" }, "413": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_413" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_503" } }, "security": [ { "accessToken": [] }, {} ] }, "delete": { "tags": [ "hub" ], "summary": "Delete a branch", "description": "`main` can't be deleted.", "operationId": "delete_api_datasets_ns_name_branch_branch", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "branch", "in": "path", "description": "A branch name.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_200" }, "400": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "409": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_409" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/datasets/{ns}/{name}/commit/{rev}": { "post": { "tags": [ "hub" ], "summary": "Commit", "description": "A Git commit on the branch `{rev}`, built on its tip. An `lfsFile` must name a file uploaded to this repository through Xet, by its SHA-256 and size. At most `hub.max_commit_bytes` and 25,000 operations.", "operationId": "post_api_datasets_ns_name_commit_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } }, { "name": "create_pr", "in": "query", "description": "Pull requests are not implemented: a true value answers `501`.", "required": false, "schema": { "type": "boolean" } } ], "requestBody": { "description": "The commit, as `huggingface_hub` sends it.", "content": { "application/x-ndjson": { "schema": { "oneOf": [ { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "enum": [ "header" ] }, "value": { "type": "object", "required": [ "summary" ], "properties": { "description": { "type": "string" }, "parentCommit": { "type": "string", "description": "The tip the commit expects; `412` if it moved." }, "summary": { "type": "string" } } } } }, { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "enum": [ "file" ] }, "value": { "type": "object", "required": [ "path", "content", "encoding" ], "properties": { "content": { "type": "string" }, "encoding": { "type": "string", "enum": [ "base64" ] }, "path": { "type": "string" } } } } }, { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "enum": [ "lfsFile" ] }, "value": { "type": "object", "required": [ "path", "algo", "oid", "size" ], "properties": { "algo": { "type": "string", "enum": [ "sha256" ] }, "oid": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "path": { "type": "string" }, "size": { "type": "integer", "minimum": 0 } } } } }, { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "enum": [ "deletedFile" ] }, "value": { "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string" } } } } }, { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "enum": [ "deletedFolder" ] }, "value": { "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string" } } } } } ], "description": "One `{\"key\", \"value\"}` object per line: a `header` first, then the operations." } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_api_datasets_ns_name_commit_rev_200" }, "400": { "$ref": "#/components/responses/post_api_datasets_ns_name_commit_rev_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_404" }, "408": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_408" }, "409": { "$ref": "#/components/responses/post_api_datasets_ns_name_commit_rev_409" }, "412": { "$ref": "#/components/responses/post_api_datasets_ns_name_commit_rev_412" }, "413": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_413" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/post_api_datasets_ns_name_commit_rev_501" }, "503": { "$ref": "#/components/responses/post_api_datasets_ns_name_commit_rev_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/datasets/{ns}/{name}/commits/{rev}": { "get": { "tags": [ "hub" ], "summary": "List commits", "description": "The history at the revision, newest first.", "operationId": "get_api_datasets_ns_name_commits_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "At most this many per page, and at most `hub.page_size`.", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "description": "Where the page starts, from the previous page's `Link`.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_commits_rev_200" }, "400": { "$ref": "#/components/responses/get_api_datasets_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/datasets/{ns}/{name}/discussions": { "get": { "tags": [ "hub" ], "summary": "Discussions", "operationId": "get_api_datasets_ns_name_discussions", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_ns_name_discussions_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] }, "post": { "tags": [ "hub" ], "summary": "Discussions", "operationId": "post_api_datasets_ns_name_discussions", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_ns_name_discussions_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/datasets/{ns}/{name}/discussions/{rest}": { "get": { "tags": [ "hub" ], "summary": "A discussion", "operationId": "get_api_datasets_ns_name_discussions_rest", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rest", "in": "path", "description": "The rest of the path. It may hold `/`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_ns_name_discussions_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] }, "post": { "tags": [ "hub" ], "summary": "A discussion", "operationId": "post_api_datasets_ns_name_discussions_rest", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rest", "in": "path", "description": "The rest of the path. It may hold `/`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_ns_name_discussions_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] }, "delete": { "tags": [ "hub" ], "summary": "A discussion", "operationId": "delete_api_datasets_ns_name_discussions_rest", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rest", "in": "path", "description": "The rest of the path. It may hold `/`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_ns_name_discussions_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] }, "patch": { "tags": [ "hub" ], "summary": "A discussion", "operationId": "patch_api_datasets_ns_name_discussions_rest", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rest", "in": "path", "description": "The rest of the path. It may hold `/`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_ns_name_discussions_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/datasets/{ns}/{name}/like": { "post": { "tags": [ "hub" ], "summary": "Like", "operationId": "post_api_datasets_ns_name_like", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_ns_name_discussions_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] }, "delete": { "tags": [ "hub" ], "summary": "Like", "operationId": "delete_api_datasets_ns_name_like", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_ns_name_discussions_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/datasets/{ns}/{name}/likers": { "get": { "tags": [ "hub" ], "summary": "Likers", "operationId": "get_api_datasets_ns_name_likers", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_ns_name_discussions_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/datasets/{ns}/{name}/paths-info/{rev}": { "post": { "tags": [ "hub" ], "summary": "Entries at paths", "description": "The entries at the paths, in request order, each path at most once; a path that names nothing is left out.", "operationId": "post_api_datasets_ns_name_paths_info_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The paths, form-encoded, at most 1 MiB.", "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "expand": { "type": "boolean" }, "paths": { "type": "array", "items": { "type": "string" }, "description": "Up to 1000; repeat the field once per path." } } } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_api_datasets_ns_name_paths_info_rev_200" }, "400": { "$ref": "#/components/responses/post_api_datasets_ns_name_paths_info_rev_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_404" }, "408": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_408" }, "413": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_413" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/datasets/{ns}/{name}/preupload/{rev}": { "post": { "tags": [ "hub" ], "summary": "Plan an upload", "description": "How to upload each file: `lfs` (through Xet) for a file at or over `hub.lfs_threshold` or matched by the revision's `.gitattributes`, else `regular`. Nothing is ignored. Needs `write`, as the commit it prepares does.", "operationId": "post_api_datasets_ns_name_preupload_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The files to upload, at most 4 MiB.", "content": { "application/json": { "schema": { "type": "object", "required": [ "files" ], "properties": { "files": { "type": "array", "items": { "type": "object", "required": [ "path", "size" ], "properties": { "path": { "type": "string" }, "sample": { "type": "string" }, "size": { "type": "integer", "minimum": 0 } } } } } } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_api_datasets_ns_name_preupload_rev_200" }, "400": { "$ref": "#/components/responses/post_api_datasets_ns_name_paths_info_rev_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_404" }, "408": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_408" }, "413": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_413" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/datasets/{ns}/{name}/refs": { "get": { "tags": [ "hub" ], "summary": "List branches and tags", "operationId": "get_api_datasets_ns_name_refs", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "include_prs", "in": "query", "description": "Also list `refs/pr/*` as `pullRequests`.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_refs_200" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/datasets/{ns}/{name}/revision/{rev}": { "get": { "tags": [ "hub" ], "summary": "Repository info", "description": "The repository, with its files at the revision: `main` without one. A repository whose initial commit failed answers without `sha`.", "operationId": "get_api_datasets_ns_name_revision_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } }, { "name": "blobs", "in": "query", "description": "Each sibling with its `blobId`, `size` and, for an LFS file, `lfs`.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_200" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/datasets/{ns}/{name}/tag/{rev}": { "post": { "tags": [ "hub" ], "summary": "Tag a revision", "description": "Tags `{rev}` with an annotated tag by the caller.", "operationId": "post_api_datasets_ns_name_tag_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The tag.", "content": { "application/json": { "schema": { "type": "object", "required": [ "tag" ], "properties": { "message": { "type": "string" }, "tag": { "type": "string" } } } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_api_datasets_ns_name_tag_rev_200" }, "400": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_404" }, "408": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_408" }, "409": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_409" }, "413": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_413" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_503" } }, "security": [ { "accessToken": [] }, {} ] }, "delete": { "tags": [ "hub" ], "summary": "Delete a tag", "description": "`{rev}` is the tag's name.", "operationId": "delete_api_datasets_ns_name_tag_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/delete_api_datasets_ns_name_tag_rev_200" }, "400": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "409": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_409" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/datasets/{ns}/{name}/tree/{rev}": { "get": { "tags": [ "hub" ], "summary": "List a folder", "description": "The folder's entries at the revision, or with `recursive` everything under it, ordered by path. Paths are read inside the commit's tree only.", "operationId": "get_api_datasets_ns_name_tree_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } }, { "name": "recursive", "in": "query", "description": "Everything under the folder.", "required": false, "schema": { "type": "boolean" } }, { "name": "expand", "in": "query", "description": "Add `lastCommit` and `securityFileStatus`.", "required": false, "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "description": "At most this many per page, and at most `hub.page_size`.", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "description": "Where the page starts, from the previous page's `Link`.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_tree_rev_200" }, "400": { "$ref": "#/components/responses/get_api_datasets_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_tree_rev_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/datasets/{ns}/{name}/tree/{rev}/{path}": { "get": { "tags": [ "hub" ], "summary": "List a folder", "description": "The folder's entries at the revision, or with `recursive` everything under it, ordered by path. Paths are read inside the commit's tree only.", "operationId": "get_api_datasets_ns_name_tree_rev_path", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "A path in the repository. It may hold `/`.", "required": true, "schema": { "type": "string" } }, { "name": "recursive", "in": "query", "description": "Everything under the folder.", "required": false, "schema": { "type": "boolean" } }, { "name": "expand", "in": "query", "description": "Add `lastCommit` and `securityFileStatus`.", "required": false, "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "description": "At most this many per page, and at most `hub.page_size`.", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "description": "Where the page starts, from the previous page's `Link`.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_tree_rev_200" }, "400": { "$ref": "#/components/responses/get_api_datasets_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_tree_rev_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/datasets/{ns}/{name}/xet-read-token/{rev}": { "get": { "tags": [ "hub" ], "summary": "CAS read token", "description": "A CAS token scoped to the repository and the operation, living `hub.token_ttl`. A revision in the path is accepted and ignored. To refresh, repeat the request.", "operationId": "get_api_datasets_ns_name_xet_read_token_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_xet_read_token_rev_200" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/datasets/{ns}/{name}/xet-write-token/{rev}": { "get": { "tags": [ "hub" ], "summary": "CAS write token", "description": "A CAS token scoped to the repository and the operation, living `hub.token_ttl`. A revision in the path is accepted and ignored. To refresh, repeat the request.", "operationId": "get_api_datasets_ns_name_xet_write_token_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_xet_read_token_rev_200" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/kernels": { "get": { "tags": [ "hub" ], "summary": "List repositories", "description": "The repositories with the route's label that the caller may read, ordered by `{namespace}/{name}` ignoring case. `full`, `config`, `cardData` and `expand` are accepted and answered with what OpenXet has; any other filter or sort answers `501`.", "operationId": "get_api_kernels", "parameters": [ { "name": "author", "in": "query", "description": "Only this namespace's repositories.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "At most this many per page, and at most `hub.page_size`.", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "description": "Where the page starts, from the previous page's `Link`.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_200" }, "400": { "$ref": "#/components/responses/get_api_datasets_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/kernels/{ns}/{name}": { "get": { "tags": [ "hub" ], "summary": "Repository info", "description": "The repository, with its files at the revision: `main` without one. A repository whose initial commit failed answers without `sha`.", "operationId": "get_api_kernels_ns_name", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "blobs", "in": "query", "description": "Each sibling with its `blobId`, `size` and, for an LFS file, `lfs`.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_200" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/kernels/{ns}/{name}/branch/{branch}": { "post": { "tags": [ "hub" ], "summary": "Create a branch", "description": "Creates `{branch}` at `startingPoint`, by default `main`'s tip. `create_branch(exist_ok=True)` treats the `409` as done.", "operationId": "post_api_kernels_ns_name_branch_branch", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "branch", "in": "path", "description": "A branch name.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Optional; an empty body starts at `main`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "startingPoint": { "type": "string", "description": "A revision." } } } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_200" }, "400": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_404" }, "408": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_408" }, "409": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_409" }, "413": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_413" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_503" } }, "security": [ { "accessToken": [] }, {} ] }, "delete": { "tags": [ "hub" ], "summary": "Delete a branch", "description": "`main` can't be deleted.", "operationId": "delete_api_kernels_ns_name_branch_branch", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "branch", "in": "path", "description": "A branch name.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_200" }, "400": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "409": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_409" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/kernels/{ns}/{name}/commit/{rev}": { "post": { "tags": [ "hub" ], "summary": "Commit", "description": "A Git commit on the branch `{rev}`, built on its tip. An `lfsFile` must name a file uploaded to this repository through Xet, by its SHA-256 and size. At most `hub.max_commit_bytes` and 25,000 operations.", "operationId": "post_api_kernels_ns_name_commit_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } }, { "name": "create_pr", "in": "query", "description": "Pull requests are not implemented: a true value answers `501`.", "required": false, "schema": { "type": "boolean" } } ], "requestBody": { "description": "The commit, as `huggingface_hub` sends it.", "content": { "application/x-ndjson": { "schema": { "oneOf": [ { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "enum": [ "header" ] }, "value": { "type": "object", "required": [ "summary" ], "properties": { "description": { "type": "string" }, "parentCommit": { "type": "string", "description": "The tip the commit expects; `412` if it moved." }, "summary": { "type": "string" } } } } }, { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "enum": [ "file" ] }, "value": { "type": "object", "required": [ "path", "content", "encoding" ], "properties": { "content": { "type": "string" }, "encoding": { "type": "string", "enum": [ "base64" ] }, "path": { "type": "string" } } } } }, { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "enum": [ "lfsFile" ] }, "value": { "type": "object", "required": [ "path", "algo", "oid", "size" ], "properties": { "algo": { "type": "string", "enum": [ "sha256" ] }, "oid": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "path": { "type": "string" }, "size": { "type": "integer", "minimum": 0 } } } } }, { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "enum": [ "deletedFile" ] }, "value": { "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string" } } } } }, { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "enum": [ "deletedFolder" ] }, "value": { "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string" } } } } } ], "description": "One `{\"key\", \"value\"}` object per line: a `header` first, then the operations." } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_api_datasets_ns_name_commit_rev_200" }, "400": { "$ref": "#/components/responses/post_api_datasets_ns_name_commit_rev_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_404" }, "408": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_408" }, "409": { "$ref": "#/components/responses/post_api_datasets_ns_name_commit_rev_409" }, "412": { "$ref": "#/components/responses/post_api_datasets_ns_name_commit_rev_412" }, "413": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_413" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/post_api_datasets_ns_name_commit_rev_501" }, "503": { "$ref": "#/components/responses/post_api_datasets_ns_name_commit_rev_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/kernels/{ns}/{name}/commits/{rev}": { "get": { "tags": [ "hub" ], "summary": "List commits", "description": "The history at the revision, newest first.", "operationId": "get_api_kernels_ns_name_commits_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "At most this many per page, and at most `hub.page_size`.", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "description": "Where the page starts, from the previous page's `Link`.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_commits_rev_200" }, "400": { "$ref": "#/components/responses/get_api_datasets_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/kernels/{ns}/{name}/discussions": { "get": { "tags": [ "hub" ], "summary": "Discussions", "operationId": "get_api_kernels_ns_name_discussions", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_ns_name_discussions_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] }, "post": { "tags": [ "hub" ], "summary": "Discussions", "operationId": "post_api_kernels_ns_name_discussions", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_ns_name_discussions_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/kernels/{ns}/{name}/discussions/{rest}": { "get": { "tags": [ "hub" ], "summary": "A discussion", "operationId": "get_api_kernels_ns_name_discussions_rest", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rest", "in": "path", "description": "The rest of the path. It may hold `/`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_ns_name_discussions_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] }, "post": { "tags": [ "hub" ], "summary": "A discussion", "operationId": "post_api_kernels_ns_name_discussions_rest", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rest", "in": "path", "description": "The rest of the path. It may hold `/`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_ns_name_discussions_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] }, "delete": { "tags": [ "hub" ], "summary": "A discussion", "operationId": "delete_api_kernels_ns_name_discussions_rest", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rest", "in": "path", "description": "The rest of the path. It may hold `/`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_ns_name_discussions_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] }, "patch": { "tags": [ "hub" ], "summary": "A discussion", "operationId": "patch_api_kernels_ns_name_discussions_rest", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rest", "in": "path", "description": "The rest of the path. It may hold `/`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_ns_name_discussions_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/kernels/{ns}/{name}/like": { "post": { "tags": [ "hub" ], "summary": "Like", "operationId": "post_api_kernels_ns_name_like", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_ns_name_discussions_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] }, "delete": { "tags": [ "hub" ], "summary": "Like", "operationId": "delete_api_kernels_ns_name_like", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_ns_name_discussions_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/kernels/{ns}/{name}/likers": { "get": { "tags": [ "hub" ], "summary": "Likers", "operationId": "get_api_kernels_ns_name_likers", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_ns_name_discussions_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/kernels/{ns}/{name}/paths-info/{rev}": { "post": { "tags": [ "hub" ], "summary": "Entries at paths", "description": "The entries at the paths, in request order, each path at most once; a path that names nothing is left out.", "operationId": "post_api_kernels_ns_name_paths_info_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The paths, form-encoded, at most 1 MiB.", "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "expand": { "type": "boolean" }, "paths": { "type": "array", "items": { "type": "string" }, "description": "Up to 1000; repeat the field once per path." } } } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_api_datasets_ns_name_paths_info_rev_200" }, "400": { "$ref": "#/components/responses/post_api_datasets_ns_name_paths_info_rev_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_404" }, "408": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_408" }, "413": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_413" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/kernels/{ns}/{name}/preupload/{rev}": { "post": { "tags": [ "hub" ], "summary": "Plan an upload", "description": "How to upload each file: `lfs` (through Xet) for a file at or over `hub.lfs_threshold` or matched by the revision's `.gitattributes`, else `regular`. Nothing is ignored. Needs `write`, as the commit it prepares does.", "operationId": "post_api_kernels_ns_name_preupload_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The files to upload, at most 4 MiB.", "content": { "application/json": { "schema": { "type": "object", "required": [ "files" ], "properties": { "files": { "type": "array", "items": { "type": "object", "required": [ "path", "size" ], "properties": { "path": { "type": "string" }, "sample": { "type": "string" }, "size": { "type": "integer", "minimum": 0 } } } } } } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_api_datasets_ns_name_preupload_rev_200" }, "400": { "$ref": "#/components/responses/post_api_datasets_ns_name_paths_info_rev_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_404" }, "408": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_408" }, "413": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_413" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/kernels/{ns}/{name}/refs": { "get": { "tags": [ "hub" ], "summary": "List branches and tags", "operationId": "get_api_kernels_ns_name_refs", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "include_prs", "in": "query", "description": "Also list `refs/pr/*` as `pullRequests`.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_refs_200" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/kernels/{ns}/{name}/revision/{rev}": { "get": { "tags": [ "hub" ], "summary": "Repository info", "description": "The repository, with its files at the revision: `main` without one. A repository whose initial commit failed answers without `sha`.", "operationId": "get_api_kernels_ns_name_revision_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } }, { "name": "blobs", "in": "query", "description": "Each sibling with its `blobId`, `size` and, for an LFS file, `lfs`.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_200" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/kernels/{ns}/{name}/tag/{rev}": { "post": { "tags": [ "hub" ], "summary": "Tag a revision", "description": "Tags `{rev}` with an annotated tag by the caller.", "operationId": "post_api_kernels_ns_name_tag_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The tag.", "content": { "application/json": { "schema": { "type": "object", "required": [ "tag" ], "properties": { "message": { "type": "string" }, "tag": { "type": "string" } } } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_api_datasets_ns_name_tag_rev_200" }, "400": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_404" }, "408": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_408" }, "409": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_409" }, "413": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_413" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_503" } }, "security": [ { "accessToken": [] }, {} ] }, "delete": { "tags": [ "hub" ], "summary": "Delete a tag", "description": "`{rev}` is the tag's name.", "operationId": "delete_api_kernels_ns_name_tag_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/delete_api_datasets_ns_name_tag_rev_200" }, "400": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "409": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_409" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/kernels/{ns}/{name}/tree/{rev}": { "get": { "tags": [ "hub" ], "summary": "List a folder", "description": "The folder's entries at the revision, or with `recursive` everything under it, ordered by path. Paths are read inside the commit's tree only.", "operationId": "get_api_kernels_ns_name_tree_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } }, { "name": "recursive", "in": "query", "description": "Everything under the folder.", "required": false, "schema": { "type": "boolean" } }, { "name": "expand", "in": "query", "description": "Add `lastCommit` and `securityFileStatus`.", "required": false, "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "description": "At most this many per page, and at most `hub.page_size`.", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "description": "Where the page starts, from the previous page's `Link`.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_tree_rev_200" }, "400": { "$ref": "#/components/responses/get_api_datasets_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_tree_rev_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/kernels/{ns}/{name}/tree/{rev}/{path}": { "get": { "tags": [ "hub" ], "summary": "List a folder", "description": "The folder's entries at the revision, or with `recursive` everything under it, ordered by path. Paths are read inside the commit's tree only.", "operationId": "get_api_kernels_ns_name_tree_rev_path", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "A path in the repository. It may hold `/`.", "required": true, "schema": { "type": "string" } }, { "name": "recursive", "in": "query", "description": "Everything under the folder.", "required": false, "schema": { "type": "boolean" } }, { "name": "expand", "in": "query", "description": "Add `lastCommit` and `securityFileStatus`.", "required": false, "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "description": "At most this many per page, and at most `hub.page_size`.", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "description": "Where the page starts, from the previous page's `Link`.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_tree_rev_200" }, "400": { "$ref": "#/components/responses/get_api_datasets_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_tree_rev_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/kernels/{ns}/{name}/xet-read-token/{rev}": { "get": { "tags": [ "hub" ], "summary": "CAS read token", "description": "A CAS token scoped to the repository and the operation, living `hub.token_ttl`. A revision in the path is accepted and ignored. To refresh, repeat the request.", "operationId": "get_api_kernels_ns_name_xet_read_token_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_xet_read_token_rev_200" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/kernels/{ns}/{name}/xet-write-token/{rev}": { "get": { "tags": [ "hub" ], "summary": "CAS write token", "description": "A CAS token scoped to the repository and the operation, living `hub.token_ttl`. A revision in the path is accepted and ignored. To refresh, repeat the request.", "operationId": "get_api_kernels_ns_name_xet_write_token_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_xet_read_token_rev_200" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/models": { "get": { "tags": [ "hub" ], "summary": "List repositories", "description": "The repositories with the route's label that the caller may read, ordered by `{namespace}/{name}` ignoring case. `full`, `config`, `cardData` and `expand` are accepted and answered with what OpenXet has; any other filter or sort answers `501`.", "operationId": "get_api_models", "parameters": [ { "name": "author", "in": "query", "description": "Only this namespace's repositories.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "At most this many per page, and at most `hub.page_size`.", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "description": "Where the page starts, from the previous page's `Link`.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_200" }, "400": { "$ref": "#/components/responses/get_api_datasets_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/models-tags-by-type": { "get": { "tags": [ "hub" ], "summary": "Model card tags", "operationId": "get_api_models_tags_by_type", "parameters": [], "responses": { "401": { "$ref": "#/components/responses/get_api_agent_harnesses_401" }, "403": { "$ref": "#/components/responses/get_api_agent_harnesses_403" }, "500": { "$ref": "#/components/responses/get_api_agent_harnesses_500" }, "501": { "$ref": "#/components/responses/get_api_agent_harnesses_501" }, "503": { "$ref": "#/components/responses/get_api_agent_harnesses_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/models/{ns}/{name}": { "get": { "tags": [ "hub" ], "summary": "Repository info", "description": "The repository, with its files at the revision: `main` without one. A repository whose initial commit failed answers without `sha`.", "operationId": "get_api_models_ns_name", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "blobs", "in": "query", "description": "Each sibling with its `blobId`, `size` and, for an LFS file, `lfs`.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_200" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/models/{ns}/{name}/branch/{branch}": { "post": { "tags": [ "hub" ], "summary": "Create a branch", "description": "Creates `{branch}` at `startingPoint`, by default `main`'s tip. `create_branch(exist_ok=True)` treats the `409` as done.", "operationId": "post_api_models_ns_name_branch_branch", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "branch", "in": "path", "description": "A branch name.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Optional; an empty body starts at `main`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "startingPoint": { "type": "string", "description": "A revision." } } } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_200" }, "400": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_404" }, "408": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_408" }, "409": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_409" }, "413": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_413" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_503" } }, "security": [ { "accessToken": [] }, {} ] }, "delete": { "tags": [ "hub" ], "summary": "Delete a branch", "description": "`main` can't be deleted.", "operationId": "delete_api_models_ns_name_branch_branch", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "branch", "in": "path", "description": "A branch name.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_200" }, "400": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "409": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_409" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/models/{ns}/{name}/commit/{rev}": { "post": { "tags": [ "hub" ], "summary": "Commit", "description": "A Git commit on the branch `{rev}`, built on its tip. An `lfsFile` must name a file uploaded to this repository through Xet, by its SHA-256 and size. At most `hub.max_commit_bytes` and 25,000 operations.", "operationId": "post_api_models_ns_name_commit_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } }, { "name": "create_pr", "in": "query", "description": "Pull requests are not implemented: a true value answers `501`.", "required": false, "schema": { "type": "boolean" } } ], "requestBody": { "description": "The commit, as `huggingface_hub` sends it.", "content": { "application/x-ndjson": { "schema": { "oneOf": [ { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "enum": [ "header" ] }, "value": { "type": "object", "required": [ "summary" ], "properties": { "description": { "type": "string" }, "parentCommit": { "type": "string", "description": "The tip the commit expects; `412` if it moved." }, "summary": { "type": "string" } } } } }, { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "enum": [ "file" ] }, "value": { "type": "object", "required": [ "path", "content", "encoding" ], "properties": { "content": { "type": "string" }, "encoding": { "type": "string", "enum": [ "base64" ] }, "path": { "type": "string" } } } } }, { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "enum": [ "lfsFile" ] }, "value": { "type": "object", "required": [ "path", "algo", "oid", "size" ], "properties": { "algo": { "type": "string", "enum": [ "sha256" ] }, "oid": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "path": { "type": "string" }, "size": { "type": "integer", "minimum": 0 } } } } }, { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "enum": [ "deletedFile" ] }, "value": { "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string" } } } } }, { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "enum": [ "deletedFolder" ] }, "value": { "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string" } } } } } ], "description": "One `{\"key\", \"value\"}` object per line: a `header` first, then the operations." } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_api_datasets_ns_name_commit_rev_200" }, "400": { "$ref": "#/components/responses/post_api_datasets_ns_name_commit_rev_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_404" }, "408": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_408" }, "409": { "$ref": "#/components/responses/post_api_datasets_ns_name_commit_rev_409" }, "412": { "$ref": "#/components/responses/post_api_datasets_ns_name_commit_rev_412" }, "413": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_413" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/post_api_datasets_ns_name_commit_rev_501" }, "503": { "$ref": "#/components/responses/post_api_datasets_ns_name_commit_rev_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/models/{ns}/{name}/commits/{rev}": { "get": { "tags": [ "hub" ], "summary": "List commits", "description": "The history at the revision, newest first.", "operationId": "get_api_models_ns_name_commits_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "At most this many per page, and at most `hub.page_size`.", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "description": "Where the page starts, from the previous page's `Link`.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_commits_rev_200" }, "400": { "$ref": "#/components/responses/get_api_datasets_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/models/{ns}/{name}/discussions": { "get": { "tags": [ "hub" ], "summary": "Discussions", "operationId": "get_api_models_ns_name_discussions", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_ns_name_discussions_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] }, "post": { "tags": [ "hub" ], "summary": "Discussions", "operationId": "post_api_models_ns_name_discussions", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_ns_name_discussions_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/models/{ns}/{name}/discussions/{rest}": { "get": { "tags": [ "hub" ], "summary": "A discussion", "operationId": "get_api_models_ns_name_discussions_rest", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rest", "in": "path", "description": "The rest of the path. It may hold `/`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_ns_name_discussions_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] }, "post": { "tags": [ "hub" ], "summary": "A discussion", "operationId": "post_api_models_ns_name_discussions_rest", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rest", "in": "path", "description": "The rest of the path. It may hold `/`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_ns_name_discussions_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] }, "delete": { "tags": [ "hub" ], "summary": "A discussion", "operationId": "delete_api_models_ns_name_discussions_rest", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rest", "in": "path", "description": "The rest of the path. It may hold `/`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_ns_name_discussions_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] }, "patch": { "tags": [ "hub" ], "summary": "A discussion", "operationId": "patch_api_models_ns_name_discussions_rest", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rest", "in": "path", "description": "The rest of the path. It may hold `/`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_ns_name_discussions_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/models/{ns}/{name}/like": { "post": { "tags": [ "hub" ], "summary": "Like", "operationId": "post_api_models_ns_name_like", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_ns_name_discussions_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] }, "delete": { "tags": [ "hub" ], "summary": "Like", "operationId": "delete_api_models_ns_name_like", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_ns_name_discussions_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/models/{ns}/{name}/likers": { "get": { "tags": [ "hub" ], "summary": "Likers", "operationId": "get_api_models_ns_name_likers", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_ns_name_discussions_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/models/{ns}/{name}/paths-info/{rev}": { "post": { "tags": [ "hub" ], "summary": "Entries at paths", "description": "The entries at the paths, in request order, each path at most once; a path that names nothing is left out.", "operationId": "post_api_models_ns_name_paths_info_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The paths, form-encoded, at most 1 MiB.", "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "expand": { "type": "boolean" }, "paths": { "type": "array", "items": { "type": "string" }, "description": "Up to 1000; repeat the field once per path." } } } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_api_datasets_ns_name_paths_info_rev_200" }, "400": { "$ref": "#/components/responses/post_api_datasets_ns_name_paths_info_rev_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_404" }, "408": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_408" }, "413": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_413" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/models/{ns}/{name}/preupload/{rev}": { "post": { "tags": [ "hub" ], "summary": "Plan an upload", "description": "How to upload each file: `lfs` (through Xet) for a file at or over `hub.lfs_threshold` or matched by the revision's `.gitattributes`, else `regular`. Nothing is ignored. Needs `write`, as the commit it prepares does.", "operationId": "post_api_models_ns_name_preupload_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The files to upload, at most 4 MiB.", "content": { "application/json": { "schema": { "type": "object", "required": [ "files" ], "properties": { "files": { "type": "array", "items": { "type": "object", "required": [ "path", "size" ], "properties": { "path": { "type": "string" }, "sample": { "type": "string" }, "size": { "type": "integer", "minimum": 0 } } } } } } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_api_datasets_ns_name_preupload_rev_200" }, "400": { "$ref": "#/components/responses/post_api_datasets_ns_name_paths_info_rev_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_404" }, "408": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_408" }, "413": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_413" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/models/{ns}/{name}/refs": { "get": { "tags": [ "hub" ], "summary": "List branches and tags", "operationId": "get_api_models_ns_name_refs", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "include_prs", "in": "query", "description": "Also list `refs/pr/*` as `pullRequests`.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_refs_200" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/models/{ns}/{name}/revision/{rev}": { "get": { "tags": [ "hub" ], "summary": "Repository info", "description": "The repository, with its files at the revision: `main` without one. A repository whose initial commit failed answers without `sha`.", "operationId": "get_api_models_ns_name_revision_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } }, { "name": "blobs", "in": "query", "description": "Each sibling with its `blobId`, `size` and, for an LFS file, `lfs`.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_200" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/models/{ns}/{name}/tag/{rev}": { "post": { "tags": [ "hub" ], "summary": "Tag a revision", "description": "Tags `{rev}` with an annotated tag by the caller.", "operationId": "post_api_models_ns_name_tag_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The tag.", "content": { "application/json": { "schema": { "type": "object", "required": [ "tag" ], "properties": { "message": { "type": "string" }, "tag": { "type": "string" } } } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_api_datasets_ns_name_tag_rev_200" }, "400": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_404" }, "408": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_408" }, "409": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_409" }, "413": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_413" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_503" } }, "security": [ { "accessToken": [] }, {} ] }, "delete": { "tags": [ "hub" ], "summary": "Delete a tag", "description": "`{rev}` is the tag's name.", "operationId": "delete_api_models_ns_name_tag_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/delete_api_datasets_ns_name_tag_rev_200" }, "400": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "409": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_409" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/models/{ns}/{name}/tree/{rev}": { "get": { "tags": [ "hub" ], "summary": "List a folder", "description": "The folder's entries at the revision, or with `recursive` everything under it, ordered by path. Paths are read inside the commit's tree only.", "operationId": "get_api_models_ns_name_tree_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } }, { "name": "recursive", "in": "query", "description": "Everything under the folder.", "required": false, "schema": { "type": "boolean" } }, { "name": "expand", "in": "query", "description": "Add `lastCommit` and `securityFileStatus`.", "required": false, "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "description": "At most this many per page, and at most `hub.page_size`.", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "description": "Where the page starts, from the previous page's `Link`.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_tree_rev_200" }, "400": { "$ref": "#/components/responses/get_api_datasets_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_tree_rev_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/models/{ns}/{name}/tree/{rev}/{path}": { "get": { "tags": [ "hub" ], "summary": "List a folder", "description": "The folder's entries at the revision, or with `recursive` everything under it, ordered by path. Paths are read inside the commit's tree only.", "operationId": "get_api_models_ns_name_tree_rev_path", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "A path in the repository. It may hold `/`.", "required": true, "schema": { "type": "string" } }, { "name": "recursive", "in": "query", "description": "Everything under the folder.", "required": false, "schema": { "type": "boolean" } }, { "name": "expand", "in": "query", "description": "Add `lastCommit` and `securityFileStatus`.", "required": false, "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "description": "At most this many per page, and at most `hub.page_size`.", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "description": "Where the page starts, from the previous page's `Link`.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_tree_rev_200" }, "400": { "$ref": "#/components/responses/get_api_datasets_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_tree_rev_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/models/{ns}/{name}/xet-read-token/{rev}": { "get": { "tags": [ "hub" ], "summary": "CAS read token", "description": "A CAS token scoped to the repository and the operation, living `hub.token_ttl`. A revision in the path is accepted and ignored. To refresh, repeat the request.", "operationId": "get_api_models_ns_name_xet_read_token_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_xet_read_token_rev_200" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/models/{ns}/{name}/xet-write-token/{rev}": { "get": { "tags": [ "hub" ], "summary": "CAS write token", "description": "A CAS token scoped to the repository and the operation, living `hub.token_ttl`. A revision in the path is accepted and ignored. To refresh, repeat the request.", "operationId": "get_api_models_ns_name_xet_write_token_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_xet_read_token_rev_200" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/openxet/v1/repos/{ns}/{name}/labels": { "get": { "tags": [ "openxet" ], "summary": "List a repository's labels", "operationId": "get_api_openxet_v1_repos_ns_name_labels", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_openxet_v1_repos_ns_name_labels_200" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/get_api_openxet_v1_repos_ns_name_labels_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/openxet/v1/repos/{ns}/{name}/labels/{label}": { "put": { "tags": [ "openxet" ], "summary": "Add a label", "description": "Adding a label the repository carries changes nothing.", "operationId": "put_api_openxet_v1_repos_ns_name_labels_label", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "label", "in": "path", "description": "A label: a lowercase slug of `a`-`z`, `0`-`9` and `-`.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_openxet_v1_repos_ns_name_labels_200" }, "400": { "$ref": "#/components/responses/put_api_openxet_v1_repos_ns_name_labels_label_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/get_api_openxet_v1_repos_ns_name_labels_404" }, "409": { "$ref": "#/components/responses/put_api_openxet_v1_repos_ns_name_labels_label_409" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] }, "delete": { "tags": [ "openxet" ], "summary": "Remove a label", "description": "Removing a label the repository doesn't carry changes nothing.", "operationId": "delete_api_openxet_v1_repos_ns_name_labels_label", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "label", "in": "path", "description": "A label: a lowercase slug of `a`-`z`, `0`-`9` and `-`.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_openxet_v1_repos_ns_name_labels_200" }, "400": { "$ref": "#/components/responses/put_api_openxet_v1_repos_ns_name_labels_label_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/get_api_openxet_v1_repos_ns_name_labels_404" }, "409": { "$ref": "#/components/responses/put_api_openxet_v1_repos_ns_name_labels_label_409" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/repos/create": { "post": { "tags": [ "hub" ], "summary": "Create a repository", "description": "Creates `{organization}/{name}` with an initial commit on `main`, labelled `type`. Creation is authorized on the namespace first, so a caller who may not create there gets the same `403` whether or not the name exists. Names are unique ignoring case and across labels.", "operationId": "post_api_repos_create", "parameters": [], "requestBody": { "description": "The repository to create.", "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The repository's name." }, "organization": { "type": "string", "description": "The namespace; the caller's own name if left out." }, "type": { "type": "string", "description": "The label the repository is seen through; `model` if left out.", "enum": [ "model", "dataset", "space", "kernel" ] }, "visibility": { "type": "string", "enum": [ "public", "private" ] } } } } }, "required": true }, "responses": { "200": { "description": "Created.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "name", "id" ], "properties": { "filesCopyPending": { "type": "boolean" }, "id": { "type": "string" }, "name": { "type": "string", "description": "`{namespace}/{name}`." }, "url": { "type": "string", "description": "The repository's URL." } } } } } }, "400": { "description": "`bad_request`: the body is not what the route takes. `invalid_name`: the namespace or name breaks a naming rule; the hint names it. `invalid_label`: the label breaks a rule.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "description": "`cas_credential`: a CAS token, which only the CAS routes take. `forbidden`: the caller may not create in the namespace.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } }, "408": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_408" }, "409": { "description": "`name_taken`: the name is taken, ignoring case. The body's `url` is the repository's URL, which `create_repo(exist_ok=True)` reads; its labels are named only to a caller who may read it.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } }, "413": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_413" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/repos/delete": { "delete": { "tags": [ "hub" ], "summary": "Delete a repository", "description": "Needs `write` on the repository and `create` in its namespace. The repository is gone at once; its data leaves through garbage collection.", "operationId": "delete_api_repos_delete", "parameters": [], "requestBody": { "description": "The repository to delete.", "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "The repository's name." }, "organization": { "type": "string", "description": "The namespace; the caller's own name if left out." }, "type": { "type": "string", "description": "The label the repository is seen through; `model` if left out.", "enum": [ "model", "dataset", "space", "kernel" ] } } } } }, "required": true }, "responses": { "200": { "description": "Deleted: `OK`.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "text/plain": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/post_api_datasets_ns_name_paths_info_rev_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "description": "`repo_not_found`: no such repository, or one the caller may not read; `delete_repo(missing_ok=True)` treats it as done.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } }, "408": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_408" }, "413": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_413" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/spaces": { "get": { "tags": [ "hub" ], "summary": "List repositories", "description": "The repositories with the route's label that the caller may read, ordered by `{namespace}/{name}` ignoring case. `full`, `config`, `cardData` and `expand` are accepted and answered with what OpenXet has; any other filter or sort answers `501`.", "operationId": "get_api_spaces", "parameters": [ { "name": "author", "in": "query", "description": "Only this namespace's repositories.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "At most this many per page, and at most `hub.page_size`.", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "description": "Where the page starts, from the previous page's `Link`.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_200" }, "400": { "$ref": "#/components/responses/get_api_datasets_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/spaces/{ns}/{name}": { "get": { "tags": [ "hub" ], "summary": "Repository info", "description": "The repository, with its files at the revision: `main` without one. A repository whose initial commit failed answers without `sha`.", "operationId": "get_api_spaces_ns_name", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "blobs", "in": "query", "description": "Each sibling with its `blobId`, `size` and, for an LFS file, `lfs`.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_200" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/spaces/{ns}/{name}/branch/{branch}": { "post": { "tags": [ "hub" ], "summary": "Create a branch", "description": "Creates `{branch}` at `startingPoint`, by default `main`'s tip. `create_branch(exist_ok=True)` treats the `409` as done.", "operationId": "post_api_spaces_ns_name_branch_branch", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "branch", "in": "path", "description": "A branch name.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "Optional; an empty body starts at `main`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "startingPoint": { "type": "string", "description": "A revision." } } } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_200" }, "400": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_404" }, "408": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_408" }, "409": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_409" }, "413": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_413" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_503" } }, "security": [ { "accessToken": [] }, {} ] }, "delete": { "tags": [ "hub" ], "summary": "Delete a branch", "description": "`main` can't be deleted.", "operationId": "delete_api_spaces_ns_name_branch_branch", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "branch", "in": "path", "description": "A branch name.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_200" }, "400": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "409": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_409" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/spaces/{ns}/{name}/commit/{rev}": { "post": { "tags": [ "hub" ], "summary": "Commit", "description": "A Git commit on the branch `{rev}`, built on its tip. An `lfsFile` must name a file uploaded to this repository through Xet, by its SHA-256 and size. At most `hub.max_commit_bytes` and 25,000 operations.", "operationId": "post_api_spaces_ns_name_commit_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } }, { "name": "create_pr", "in": "query", "description": "Pull requests are not implemented: a true value answers `501`.", "required": false, "schema": { "type": "boolean" } } ], "requestBody": { "description": "The commit, as `huggingface_hub` sends it.", "content": { "application/x-ndjson": { "schema": { "oneOf": [ { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "enum": [ "header" ] }, "value": { "type": "object", "required": [ "summary" ], "properties": { "description": { "type": "string" }, "parentCommit": { "type": "string", "description": "The tip the commit expects; `412` if it moved." }, "summary": { "type": "string" } } } } }, { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "enum": [ "file" ] }, "value": { "type": "object", "required": [ "path", "content", "encoding" ], "properties": { "content": { "type": "string" }, "encoding": { "type": "string", "enum": [ "base64" ] }, "path": { "type": "string" } } } } }, { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "enum": [ "lfsFile" ] }, "value": { "type": "object", "required": [ "path", "algo", "oid", "size" ], "properties": { "algo": { "type": "string", "enum": [ "sha256" ] }, "oid": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "path": { "type": "string" }, "size": { "type": "integer", "minimum": 0 } } } } }, { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "enum": [ "deletedFile" ] }, "value": { "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string" } } } } }, { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string", "enum": [ "deletedFolder" ] }, "value": { "type": "object", "required": [ "path" ], "properties": { "path": { "type": "string" } } } } } ], "description": "One `{\"key\", \"value\"}` object per line: a `header` first, then the operations." } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_api_datasets_ns_name_commit_rev_200" }, "400": { "$ref": "#/components/responses/post_api_datasets_ns_name_commit_rev_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_404" }, "408": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_408" }, "409": { "$ref": "#/components/responses/post_api_datasets_ns_name_commit_rev_409" }, "412": { "$ref": "#/components/responses/post_api_datasets_ns_name_commit_rev_412" }, "413": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_413" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/post_api_datasets_ns_name_commit_rev_501" }, "503": { "$ref": "#/components/responses/post_api_datasets_ns_name_commit_rev_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/spaces/{ns}/{name}/commits/{rev}": { "get": { "tags": [ "hub" ], "summary": "List commits", "description": "The history at the revision, newest first.", "operationId": "get_api_spaces_ns_name_commits_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "At most this many per page, and at most `hub.page_size`.", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "description": "Where the page starts, from the previous page's `Link`.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_commits_rev_200" }, "400": { "$ref": "#/components/responses/get_api_datasets_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/spaces/{ns}/{name}/discussions": { "get": { "tags": [ "hub" ], "summary": "Discussions", "operationId": "get_api_spaces_ns_name_discussions", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_ns_name_discussions_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] }, "post": { "tags": [ "hub" ], "summary": "Discussions", "operationId": "post_api_spaces_ns_name_discussions", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_ns_name_discussions_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/spaces/{ns}/{name}/discussions/{rest}": { "get": { "tags": [ "hub" ], "summary": "A discussion", "operationId": "get_api_spaces_ns_name_discussions_rest", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rest", "in": "path", "description": "The rest of the path. It may hold `/`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_ns_name_discussions_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] }, "post": { "tags": [ "hub" ], "summary": "A discussion", "operationId": "post_api_spaces_ns_name_discussions_rest", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rest", "in": "path", "description": "The rest of the path. It may hold `/`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_ns_name_discussions_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] }, "delete": { "tags": [ "hub" ], "summary": "A discussion", "operationId": "delete_api_spaces_ns_name_discussions_rest", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rest", "in": "path", "description": "The rest of the path. It may hold `/`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_ns_name_discussions_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] }, "patch": { "tags": [ "hub" ], "summary": "A discussion", "operationId": "patch_api_spaces_ns_name_discussions_rest", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rest", "in": "path", "description": "The rest of the path. It may hold `/`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_ns_name_discussions_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/spaces/{ns}/{name}/like": { "post": { "tags": [ "hub" ], "summary": "Like", "operationId": "post_api_spaces_ns_name_like", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_ns_name_discussions_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] }, "delete": { "tags": [ "hub" ], "summary": "Like", "operationId": "delete_api_spaces_ns_name_like", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_ns_name_discussions_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/spaces/{ns}/{name}/likers": { "get": { "tags": [ "hub" ], "summary": "Likers", "operationId": "get_api_spaces_ns_name_likers", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "501": { "$ref": "#/components/responses/get_api_datasets_ns_name_discussions_501" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/spaces/{ns}/{name}/paths-info/{rev}": { "post": { "tags": [ "hub" ], "summary": "Entries at paths", "description": "The entries at the paths, in request order, each path at most once; a path that names nothing is left out.", "operationId": "post_api_spaces_ns_name_paths_info_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The paths, form-encoded, at most 1 MiB.", "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "expand": { "type": "boolean" }, "paths": { "type": "array", "items": { "type": "string" }, "description": "Up to 1000; repeat the field once per path." } } } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_api_datasets_ns_name_paths_info_rev_200" }, "400": { "$ref": "#/components/responses/post_api_datasets_ns_name_paths_info_rev_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_404" }, "408": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_408" }, "413": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_413" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/spaces/{ns}/{name}/preupload/{rev}": { "post": { "tags": [ "hub" ], "summary": "Plan an upload", "description": "How to upload each file: `lfs` (through Xet) for a file at or over `hub.lfs_threshold` or matched by the revision's `.gitattributes`, else `regular`. Nothing is ignored. Needs `write`, as the commit it prepares does.", "operationId": "post_api_spaces_ns_name_preupload_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The files to upload, at most 4 MiB.", "content": { "application/json": { "schema": { "type": "object", "required": [ "files" ], "properties": { "files": { "type": "array", "items": { "type": "object", "required": [ "path", "size" ], "properties": { "path": { "type": "string" }, "sample": { "type": "string" }, "size": { "type": "integer", "minimum": 0 } } } } } } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_api_datasets_ns_name_preupload_rev_200" }, "400": { "$ref": "#/components/responses/post_api_datasets_ns_name_paths_info_rev_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_404" }, "408": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_408" }, "413": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_413" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/spaces/{ns}/{name}/refs": { "get": { "tags": [ "hub" ], "summary": "List branches and tags", "operationId": "get_api_spaces_ns_name_refs", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "include_prs", "in": "query", "description": "Also list `refs/pr/*` as `pullRequests`.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_refs_200" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/spaces/{ns}/{name}/revision/{rev}": { "get": { "tags": [ "hub" ], "summary": "Repository info", "description": "The repository, with its files at the revision: `main` without one. A repository whose initial commit failed answers without `sha`.", "operationId": "get_api_spaces_ns_name_revision_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } }, { "name": "blobs", "in": "query", "description": "Each sibling with its `blobId`, `size` and, for an LFS file, `lfs`.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_200" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/spaces/{ns}/{name}/tag/{rev}": { "post": { "tags": [ "hub" ], "summary": "Tag a revision", "description": "Tags `{rev}` with an annotated tag by the caller.", "operationId": "post_api_spaces_ns_name_tag_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The tag.", "content": { "application/json": { "schema": { "type": "object", "required": [ "tag" ], "properties": { "message": { "type": "string" }, "tag": { "type": "string" } } } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_api_datasets_ns_name_tag_rev_200" }, "400": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_404" }, "408": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_408" }, "409": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_409" }, "413": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_413" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_503" } }, "security": [ { "accessToken": [] }, {} ] }, "delete": { "tags": [ "hub" ], "summary": "Delete a tag", "description": "`{rev}` is the tag's name.", "operationId": "delete_api_spaces_ns_name_tag_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/delete_api_datasets_ns_name_tag_rev_200" }, "400": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "409": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_409" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/spaces/{ns}/{name}/tree/{rev}": { "get": { "tags": [ "hub" ], "summary": "List a folder", "description": "The folder's entries at the revision, or with `recursive` everything under it, ordered by path. Paths are read inside the commit's tree only.", "operationId": "get_api_spaces_ns_name_tree_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } }, { "name": "recursive", "in": "query", "description": "Everything under the folder.", "required": false, "schema": { "type": "boolean" } }, { "name": "expand", "in": "query", "description": "Add `lastCommit` and `securityFileStatus`.", "required": false, "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "description": "At most this many per page, and at most `hub.page_size`.", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "description": "Where the page starts, from the previous page's `Link`.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_tree_rev_200" }, "400": { "$ref": "#/components/responses/get_api_datasets_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_tree_rev_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/spaces/{ns}/{name}/tree/{rev}/{path}": { "get": { "tags": [ "hub" ], "summary": "List a folder", "description": "The folder's entries at the revision, or with `recursive` everything under it, ordered by path. Paths are read inside the commit's tree only.", "operationId": "get_api_spaces_ns_name_tree_rev_path", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "A path in the repository. It may hold `/`.", "required": true, "schema": { "type": "string" } }, { "name": "recursive", "in": "query", "description": "Everything under the folder.", "required": false, "schema": { "type": "boolean" } }, { "name": "expand", "in": "query", "description": "Add `lastCommit` and `securityFileStatus`.", "required": false, "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "description": "At most this many per page, and at most `hub.page_size`.", "required": false, "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "description": "Where the page starts, from the previous page's `Link`.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_tree_rev_200" }, "400": { "$ref": "#/components/responses/get_api_datasets_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/get_api_datasets_ns_name_tree_rev_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/spaces/{ns}/{name}/xet-read-token/{rev}": { "get": { "tags": [ "hub" ], "summary": "CAS read token", "description": "A CAS token scoped to the repository and the operation, living `hub.token_ttl`. A revision in the path is accepted and ignored. To refresh, repeat the request.", "operationId": "get_api_spaces_ns_name_xet_read_token_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_xet_read_token_rev_200" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/spaces/{ns}/{name}/xet-write-token/{rev}": { "get": { "tags": [ "hub" ], "summary": "CAS write token", "description": "A CAS token scoped to the repository and the operation, living `hub.token_ttl`. A revision in the path is accepted and ignored. To refresh, repeat the request.", "operationId": "get_api_spaces_ns_name_xet_write_token_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_xet_read_token_rev_200" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/users/{user}/likes": { "get": { "tags": [ "hub" ], "summary": "A user's likes", "operationId": "get_api_users_user_likes", "parameters": [ { "name": "user", "in": "path", "description": "A user name.", "required": true, "schema": { "type": "string" } } ], "responses": { "401": { "$ref": "#/components/responses/get_api_agent_harnesses_401" }, "403": { "$ref": "#/components/responses/get_api_agent_harnesses_403" }, "500": { "$ref": "#/components/responses/get_api_agent_harnesses_500" }, "501": { "$ref": "#/components/responses/get_api_agent_harnesses_501" }, "503": { "$ref": "#/components/responses/get_api_agent_harnesses_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/validate-yaml": { "post": { "tags": [ "hub" ], "summary": "Validate a model card", "description": "Every commit adding a `README.md` posts it here first. OpenXet checks the request's shape, not the card's metadata.", "operationId": "post_api_validate_yaml", "parameters": [], "requestBody": { "description": "The card, at most 16 MiB.", "content": { "application/json": { "schema": { "type": "object", "required": [ "content" ], "properties": { "content": { "type": "string" } } } } }, "required": true }, "responses": { "200": { "description": "No errors and no warnings.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "errors", "warnings" ], "properties": { "errors": { "type": "array" }, "warnings": { "type": "array" } } } } } }, "400": { "$ref": "#/components/responses/post_api_datasets_ns_name_paths_info_rev_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "408": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_408" }, "413": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_413" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/api/whoami-v2": { "get": { "tags": [ "hub" ], "summary": "Who the token acts for", "description": "The token's user and organizations, in huggingface.co's shape. `role` is `fineGrained`: what the token may do is decided per repository by the operator's rules.", "operationId": "get_api_whoami_v2", "parameters": [], "responses": { "200": { "description": "The user.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "type", "id", "name", "orgs", "auth" ], "properties": { "auth": { "type": "object", "properties": { "accessToken": { "type": "object", "properties": { "displayName": { "type": "string", "description": "The name `hf auth login` stores the token under." }, "role": { "type": "string", "enum": [ "fineGrained" ] } } }, "type": { "type": "string", "enum": [ "access_token" ] } } }, "avatarUrl": { "type": "string" }, "fullname": { "type": "string" }, "id": { "type": "string" }, "isPro": { "type": "boolean" }, "name": { "type": "string" }, "orgs": { "type": "array", "items": { "type": "object", "required": [ "name" ], "properties": { "avatarUrl": { "type": "string" }, "fullname": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "org" ] } } } }, "type": { "type": "string", "enum": [ "user" ] } } } } } }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/datasets/{ns}/{name}/git-receive-pack": { "post": { "tags": [ "git" ], "summary": "Push", "description": "One push, whose refs move only through the fenced commit transaction. The first push to a missing repository creates it when the caller may create in its namespace.", "operationId": "post_datasets_ns_name_git_receive_pack", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "Content-Encoding", "in": "header", "description": "`gzip`, as git sends a large fetch request; inflated as it arrives.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "description": "Git's request, in pkt-lines. Only this type is taken, as `git http-backend` does, so a browser can't send it without a CORS preflight.", "content": { "application/x-git-receive-pack-request": { "schema": { "type": "string", "contentMediaType": "application/x-git-receive-pack-request" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_200" }, "401": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_401" }, "403": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_403" }, "404": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_404" }, "408": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_408" }, "413": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_413" }, "415": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_415" }, "500": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_500" }, "503": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_503" } }, "security": [ { "accessToken": [] }, { "accessTokenBasic": [] }, {} ] } }, "/datasets/{ns}/{name}/git-upload-pack": { "post": { "tags": [ "git" ], "summary": "Fetch", "description": "One stateless fetch or `ls-refs` request. A want the refs don't reach is refused.", "operationId": "post_datasets_ns_name_git_upload_pack", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "Content-Encoding", "in": "header", "description": "`gzip`, as git sends a large fetch request; inflated as it arrives.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "description": "Git's request, in pkt-lines. Only this type is taken, as `git http-backend` does, so a browser can't send it without a CORS preflight.", "content": { "application/x-git-upload-pack-request": { "schema": { "type": "string", "contentMediaType": "application/x-git-upload-pack-request" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_datasets_ns_name_git_upload_pack_200" }, "401": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_401" }, "403": { "$ref": "#/components/responses/post_datasets_ns_name_git_upload_pack_403" }, "404": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_404" }, "408": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_408" }, "415": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_415" }, "429": { "$ref": "#/components/responses/post_datasets_ns_name_git_upload_pack_429" }, "500": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_500" }, "503": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_503" } }, "security": [ { "accessToken": [] }, { "accessTokenBasic": [] }, {} ] } }, "/datasets/{ns}/{name}/info/lfs/objects/batch": { "post": { "tags": [ "lfs" ], "summary": "Git LFS batch", "description": "Under every Git URL, `{name}` with or without `.git`, unprefixed (whatever the labels) or under `/datasets`, `/spaces` and `/kernels`. A `401` carries `WWW-Authenticate` and `LFS-Authenticate: Basic realm=\"openxet\"`, so `git-lfs` asks its credential helpers. Every answer is `Cache-Control: no-store`.", "operationId": "post_datasets_ns_name_info_lfs_objects_batch", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The batch, as `git-lfs` sends it, at most 1 MiB. An upload batch to a missing repository the caller may create in creates it.", "content": { "application/vnd.git-lfs+json": { "schema": { "type": "object", "required": [ "operation", "objects" ], "properties": { "hash_algo": { "type": "string", "enum": [ "sha256" ] }, "objects": { "type": "array", "items": { "type": "object", "required": [ "oid", "size" ], "properties": { "oid": { "type": "string", "description": "The file's SHA-256, lowercase hex." }, "size": { "type": "integer" } } }, "description": "At most 1,000." }, "operation": { "type": "string", "enum": [ "upload", "download" ] }, "transfers": { "type": "array", "items": { "type": "string" }, "description": "Uploads offering `xet` answer `xet`; others get the object error `501` naming `git-xet`. Downloads are `basic`." } } } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_datasets_ns_name_info_lfs_objects_batch_200" }, "400": { "$ref": "#/components/responses/post_api_datasets_ns_name_paths_info_rev_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "408": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_408" }, "409": { "$ref": "#/components/responses/post_datasets_ns_name_info_lfs_objects_batch_409" }, "413": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_413" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, { "accessTokenBasic": [] }, {} ] } }, "/datasets/{ns}/{name}/info/lfs/objects/verify": { "post": { "tags": [ "lfs" ], "summary": "Git LFS verify", "description": "Under every Git URL, `{name}` with or without `.git`, unprefixed (whatever the labels) or under `/datasets`, `/spaces` and `/kernels`. A `401` carries `WWW-Authenticate` and `LFS-Authenticate: Basic realm=\"openxet\"`, so `git-lfs` asks its credential helpers. Every answer is `Cache-Control: no-store`.", "operationId": "post_datasets_ns_name_info_lfs_objects_verify", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The object an upload sent.", "content": { "application/vnd.git-lfs+json": { "schema": { "type": "object", "required": [ "oid", "size" ], "properties": { "oid": { "type": "string", "description": "The file's SHA-256, lowercase hex." }, "size": { "type": "integer" } } } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_datasets_ns_name_info_lfs_objects_verify_200" }, "400": { "$ref": "#/components/responses/post_api_datasets_ns_name_paths_info_rev_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/post_datasets_ns_name_info_lfs_objects_verify_404" }, "408": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_408" }, "413": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_413" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, { "accessTokenBasic": [] }, {} ] } }, "/datasets/{ns}/{name}/info/lfs/xet-read-token": { "get": { "tags": [ "lfs" ], "summary": "CAS read token", "description": "A CAS token scoped to the repository and the operation, living `hub.token_ttl`. A revision in the path is accepted and ignored. To refresh, repeat the request.", "operationId": "get_datasets_ns_name_info_lfs_xet_read_token", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_xet_read_token_rev_200" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, { "accessTokenBasic": [] }, {} ] } }, "/datasets/{ns}/{name}/info/lfs/xet-write-token": { "get": { "tags": [ "lfs" ], "summary": "CAS write token", "description": "A CAS token scoped to the repository and the operation, living `hub.token_ttl`. A revision in the path is accepted and ignored. To refresh, repeat the request.", "operationId": "get_datasets_ns_name_info_lfs_xet_write_token", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_xet_read_token_rev_200" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, { "accessTokenBasic": [] }, {} ] } }, "/datasets/{ns}/{name}/info/refs": { "get": { "tags": [ "git" ], "summary": "Ref advertisement", "description": "Smart HTTP's first request, for a clone, fetch or push. `{name}` may end in `.git`. The unprefixed URL sees every repository whatever its labels; `/datasets`, `/spaces` and `/kernels` see it through that label. For a push to a missing repository the caller may create in its namespace, it advertises an empty repository.", "operationId": "get_datasets_ns_name_info_refs", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "service", "in": "query", "description": "The service; a request without one is the dumb protocol's, answered `404`.", "required": true, "schema": { "type": "string", "enum": [ "git-upload-pack", "git-receive-pack" ] } }, { "name": "Git-Protocol", "in": "header", "description": "`version=2` for protocol v2.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_datasets_ns_name_info_refs_200" }, "401": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_401" }, "403": { "$ref": "#/components/responses/post_datasets_ns_name_git_upload_pack_403" }, "404": { "$ref": "#/components/responses/get_datasets_ns_name_info_refs_404" }, "500": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_500" }, "503": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_503" } }, "security": [ { "accessToken": [] }, { "accessTokenBasic": [] }, {} ] } }, "/datasets/{ns}/{name}/resolve/{rev}/": { "get": { "tags": [ "hub" ], "summary": "Download a file", "description": "A file at a revision, as `hf_hub_download` and plain HTTP clients read it; `HEAD` answers the same without a body. A file stored in Git answers inline, `Range` included. A Xet file redirects to the file gateway, with the headers `huggingface_hub` reads. The model view has no prefix; the other types are under `/datasets`, `/spaces` and `/kernels`. The path is read inside the commit's tree only, so `.`, `..`, a folder or the root name no file.", "operationId": "get_datasets_ns_name_resolve_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } }, { "name": "Range", "in": "header", "description": "One byte range: `bytes=start-end`, `bytes=start-` or `bytes=-length`.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_200" }, "206": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_206" }, "302": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_302" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_404" }, "413": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_413" }, "416": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_416" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/datasets/{ns}/{name}/resolve/{rev}/{path}": { "get": { "tags": [ "hub" ], "summary": "Download a file", "description": "A file at a revision, as `hf_hub_download` and plain HTTP clients read it; `HEAD` answers the same without a body. A file stored in Git answers inline, `Range` included. A Xet file redirects to the file gateway, with the headers `huggingface_hub` reads. The model view has no prefix; the other types are under `/datasets`, `/spaces` and `/kernels`. The path is read inside the commit's tree only, so `.`, `..`, a folder or the root name no file.", "operationId": "get_datasets_ns_name_resolve_rev_path", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "A path in the repository. It may hold `/`.", "required": true, "schema": { "type": "string" } }, { "name": "Range", "in": "header", "description": "One byte range: `bytes=start-end`, `bytes=start-` or `bytes=-length`.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_200" }, "206": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_206" }, "302": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_302" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_404" }, "413": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_413" }, "416": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_416" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/healthz": { "get": { "tags": [ "health" ], "summary": "Liveness", "operationId": "get_healthz", "parameters": [], "responses": { "200": { "description": "The process is up and serving HTTP.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "ok" ] } } } } } }, "500": { "$ref": "#/components/responses/get_healthz_500" }, "503": { "$ref": "#/components/responses/get_healthz_503" } }, "security": [] } }, "/kernels/{ns}/{name}/git-receive-pack": { "post": { "tags": [ "git" ], "summary": "Push", "description": "One push, whose refs move only through the fenced commit transaction. The first push to a missing repository creates it when the caller may create in its namespace.", "operationId": "post_kernels_ns_name_git_receive_pack", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "Content-Encoding", "in": "header", "description": "`gzip`, as git sends a large fetch request; inflated as it arrives.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "description": "Git's request, in pkt-lines. Only this type is taken, as `git http-backend` does, so a browser can't send it without a CORS preflight.", "content": { "application/x-git-receive-pack-request": { "schema": { "type": "string", "contentMediaType": "application/x-git-receive-pack-request" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_200" }, "401": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_401" }, "403": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_403" }, "404": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_404" }, "408": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_408" }, "413": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_413" }, "415": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_415" }, "500": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_500" }, "503": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_503" } }, "security": [ { "accessToken": [] }, { "accessTokenBasic": [] }, {} ] } }, "/kernels/{ns}/{name}/git-upload-pack": { "post": { "tags": [ "git" ], "summary": "Fetch", "description": "One stateless fetch or `ls-refs` request. A want the refs don't reach is refused.", "operationId": "post_kernels_ns_name_git_upload_pack", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "Content-Encoding", "in": "header", "description": "`gzip`, as git sends a large fetch request; inflated as it arrives.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "description": "Git's request, in pkt-lines. Only this type is taken, as `git http-backend` does, so a browser can't send it without a CORS preflight.", "content": { "application/x-git-upload-pack-request": { "schema": { "type": "string", "contentMediaType": "application/x-git-upload-pack-request" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_datasets_ns_name_git_upload_pack_200" }, "401": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_401" }, "403": { "$ref": "#/components/responses/post_datasets_ns_name_git_upload_pack_403" }, "404": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_404" }, "408": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_408" }, "415": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_415" }, "429": { "$ref": "#/components/responses/post_datasets_ns_name_git_upload_pack_429" }, "500": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_500" }, "503": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_503" } }, "security": [ { "accessToken": [] }, { "accessTokenBasic": [] }, {} ] } }, "/kernels/{ns}/{name}/info/lfs/objects/batch": { "post": { "tags": [ "lfs" ], "summary": "Git LFS batch", "description": "Under every Git URL, `{name}` with or without `.git`, unprefixed (whatever the labels) or under `/datasets`, `/spaces` and `/kernels`. A `401` carries `WWW-Authenticate` and `LFS-Authenticate: Basic realm=\"openxet\"`, so `git-lfs` asks its credential helpers. Every answer is `Cache-Control: no-store`.", "operationId": "post_kernels_ns_name_info_lfs_objects_batch", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The batch, as `git-lfs` sends it, at most 1 MiB. An upload batch to a missing repository the caller may create in creates it.", "content": { "application/vnd.git-lfs+json": { "schema": { "type": "object", "required": [ "operation", "objects" ], "properties": { "hash_algo": { "type": "string", "enum": [ "sha256" ] }, "objects": { "type": "array", "items": { "type": "object", "required": [ "oid", "size" ], "properties": { "oid": { "type": "string", "description": "The file's SHA-256, lowercase hex." }, "size": { "type": "integer" } } }, "description": "At most 1,000." }, "operation": { "type": "string", "enum": [ "upload", "download" ] }, "transfers": { "type": "array", "items": { "type": "string" }, "description": "Uploads offering `xet` answer `xet`; others get the object error `501` naming `git-xet`. Downloads are `basic`." } } } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_datasets_ns_name_info_lfs_objects_batch_200" }, "400": { "$ref": "#/components/responses/post_api_datasets_ns_name_paths_info_rev_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "408": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_408" }, "409": { "$ref": "#/components/responses/post_datasets_ns_name_info_lfs_objects_batch_409" }, "413": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_413" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, { "accessTokenBasic": [] }, {} ] } }, "/kernels/{ns}/{name}/info/lfs/objects/verify": { "post": { "tags": [ "lfs" ], "summary": "Git LFS verify", "description": "Under every Git URL, `{name}` with or without `.git`, unprefixed (whatever the labels) or under `/datasets`, `/spaces` and `/kernels`. A `401` carries `WWW-Authenticate` and `LFS-Authenticate: Basic realm=\"openxet\"`, so `git-lfs` asks its credential helpers. Every answer is `Cache-Control: no-store`.", "operationId": "post_kernels_ns_name_info_lfs_objects_verify", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The object an upload sent.", "content": { "application/vnd.git-lfs+json": { "schema": { "type": "object", "required": [ "oid", "size" ], "properties": { "oid": { "type": "string", "description": "The file's SHA-256, lowercase hex." }, "size": { "type": "integer" } } } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_datasets_ns_name_info_lfs_objects_verify_200" }, "400": { "$ref": "#/components/responses/post_api_datasets_ns_name_paths_info_rev_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/post_datasets_ns_name_info_lfs_objects_verify_404" }, "408": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_408" }, "413": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_413" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, { "accessTokenBasic": [] }, {} ] } }, "/kernels/{ns}/{name}/info/lfs/xet-read-token": { "get": { "tags": [ "lfs" ], "summary": "CAS read token", "description": "A CAS token scoped to the repository and the operation, living `hub.token_ttl`. A revision in the path is accepted and ignored. To refresh, repeat the request.", "operationId": "get_kernels_ns_name_info_lfs_xet_read_token", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_xet_read_token_rev_200" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, { "accessTokenBasic": [] }, {} ] } }, "/kernels/{ns}/{name}/info/lfs/xet-write-token": { "get": { "tags": [ "lfs" ], "summary": "CAS write token", "description": "A CAS token scoped to the repository and the operation, living `hub.token_ttl`. A revision in the path is accepted and ignored. To refresh, repeat the request.", "operationId": "get_kernels_ns_name_info_lfs_xet_write_token", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_xet_read_token_rev_200" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, { "accessTokenBasic": [] }, {} ] } }, "/kernels/{ns}/{name}/info/refs": { "get": { "tags": [ "git" ], "summary": "Ref advertisement", "description": "Smart HTTP's first request, for a clone, fetch or push. `{name}` may end in `.git`. The unprefixed URL sees every repository whatever its labels; `/datasets`, `/spaces` and `/kernels` see it through that label. For a push to a missing repository the caller may create in its namespace, it advertises an empty repository.", "operationId": "get_kernels_ns_name_info_refs", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "service", "in": "query", "description": "The service; a request without one is the dumb protocol's, answered `404`.", "required": true, "schema": { "type": "string", "enum": [ "git-upload-pack", "git-receive-pack" ] } }, { "name": "Git-Protocol", "in": "header", "description": "`version=2` for protocol v2.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_datasets_ns_name_info_refs_200" }, "401": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_401" }, "403": { "$ref": "#/components/responses/post_datasets_ns_name_git_upload_pack_403" }, "404": { "$ref": "#/components/responses/get_datasets_ns_name_info_refs_404" }, "500": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_500" }, "503": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_503" } }, "security": [ { "accessToken": [] }, { "accessTokenBasic": [] }, {} ] } }, "/kernels/{ns}/{name}/resolve/{rev}/": { "get": { "tags": [ "hub" ], "summary": "Download a file", "description": "A file at a revision, as `hf_hub_download` and plain HTTP clients read it; `HEAD` answers the same without a body. A file stored in Git answers inline, `Range` included. A Xet file redirects to the file gateway, with the headers `huggingface_hub` reads. The model view has no prefix; the other types are under `/datasets`, `/spaces` and `/kernels`. The path is read inside the commit's tree only, so `.`, `..`, a folder or the root name no file.", "operationId": "get_kernels_ns_name_resolve_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } }, { "name": "Range", "in": "header", "description": "One byte range: `bytes=start-end`, `bytes=start-` or `bytes=-length`.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_200" }, "206": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_206" }, "302": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_302" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_404" }, "413": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_413" }, "416": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_416" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/kernels/{ns}/{name}/resolve/{rev}/{path}": { "get": { "tags": [ "hub" ], "summary": "Download a file", "description": "A file at a revision, as `hf_hub_download` and plain HTTP clients read it; `HEAD` answers the same without a body. A file stored in Git answers inline, `Range` included. A Xet file redirects to the file gateway, with the headers `huggingface_hub` reads. The model view has no prefix; the other types are under `/datasets`, `/spaces` and `/kernels`. The path is read inside the commit's tree only, so `.`, `..`, a folder or the root name no file.", "operationId": "get_kernels_ns_name_resolve_rev_path", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "A path in the repository. It may hold `/`.", "required": true, "schema": { "type": "string" } }, { "name": "Range", "in": "header", "description": "One byte range: `bytes=start-end`, `bytes=start-` or `bytes=-length`.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_200" }, "206": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_206" }, "302": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_302" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_404" }, "413": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_413" }, "416": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_416" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/openapi.json": { "get": { "tags": [ "meta" ], "summary": "This document", "description": "What `openxet openapi` prints, byte for byte.", "operationId": "get_openapi_json", "parameters": [], "responses": { "200": { "description": "The OpenAPI 3.1 document.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "500": { "$ref": "#/components/responses/get_healthz_500" }, "503": { "$ref": "#/components/responses/get_healthz_503" } }, "security": [] } }, "/readyz": { "get": { "tags": [ "health" ], "summary": "Readiness", "description": "Ready once the index answers a read of its tables and the bucket takes a write. Each component is probed at most once a second, however often this is called.", "operationId": "get_readyz", "parameters": [], "responses": { "200": { "description": "The index and the bucket are open and answer.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "ready" ] } } } } } }, "500": { "$ref": "#/components/responses/get_healthz_500" }, "503": { "description": "`not_ready`: the server is starting. `Retry-After: 1`. `unavailable`: the index or the bucket failed or took over a second; the message names `index` or `storage`, never the cause.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [] } }, "/shards": { "post": { "tags": [ "cas" ], "summary": "Register files", "description": "`POST /v1/shards` without the version, which `git-xet` 0.2.1 sends and huggingface.co's CAS accepts.", "operationId": "post_shards", "parameters": [], "requestBody": { "description": "An upload shard (https://huggingface.co/docs/xet/shard), at most 64 MiB.", "content": { "application/octet-stream": { "schema": { "type": "string", "contentMediaType": "application/octet-stream" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_shards_200" }, "400": { "$ref": "#/components/responses/post_shards_400" }, "401": { "$ref": "#/components/responses/post_shards_401" }, "403": { "$ref": "#/components/responses/post_shards_403" }, "408": { "$ref": "#/components/responses/post_shards_408" }, "413": { "$ref": "#/components/responses/post_shards_413" }, "500": { "$ref": "#/components/responses/get_healthz_500" }, "503": { "$ref": "#/components/responses/post_shards_503" } }, "security": [ { "casToken": [] } ] } }, "/spaces/{ns}/{name}/git-receive-pack": { "post": { "tags": [ "git" ], "summary": "Push", "description": "One push, whose refs move only through the fenced commit transaction. The first push to a missing repository creates it when the caller may create in its namespace.", "operationId": "post_spaces_ns_name_git_receive_pack", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "Content-Encoding", "in": "header", "description": "`gzip`, as git sends a large fetch request; inflated as it arrives.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "description": "Git's request, in pkt-lines. Only this type is taken, as `git http-backend` does, so a browser can't send it without a CORS preflight.", "content": { "application/x-git-receive-pack-request": { "schema": { "type": "string", "contentMediaType": "application/x-git-receive-pack-request" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_200" }, "401": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_401" }, "403": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_403" }, "404": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_404" }, "408": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_408" }, "413": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_413" }, "415": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_415" }, "500": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_500" }, "503": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_503" } }, "security": [ { "accessToken": [] }, { "accessTokenBasic": [] }, {} ] } }, "/spaces/{ns}/{name}/git-upload-pack": { "post": { "tags": [ "git" ], "summary": "Fetch", "description": "One stateless fetch or `ls-refs` request. A want the refs don't reach is refused.", "operationId": "post_spaces_ns_name_git_upload_pack", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "Content-Encoding", "in": "header", "description": "`gzip`, as git sends a large fetch request; inflated as it arrives.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "description": "Git's request, in pkt-lines. Only this type is taken, as `git http-backend` does, so a browser can't send it without a CORS preflight.", "content": { "application/x-git-upload-pack-request": { "schema": { "type": "string", "contentMediaType": "application/x-git-upload-pack-request" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_datasets_ns_name_git_upload_pack_200" }, "401": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_401" }, "403": { "$ref": "#/components/responses/post_datasets_ns_name_git_upload_pack_403" }, "404": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_404" }, "408": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_408" }, "415": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_415" }, "429": { "$ref": "#/components/responses/post_datasets_ns_name_git_upload_pack_429" }, "500": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_500" }, "503": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_503" } }, "security": [ { "accessToken": [] }, { "accessTokenBasic": [] }, {} ] } }, "/spaces/{ns}/{name}/info/lfs/objects/batch": { "post": { "tags": [ "lfs" ], "summary": "Git LFS batch", "description": "Under every Git URL, `{name}` with or without `.git`, unprefixed (whatever the labels) or under `/datasets`, `/spaces` and `/kernels`. A `401` carries `WWW-Authenticate` and `LFS-Authenticate: Basic realm=\"openxet\"`, so `git-lfs` asks its credential helpers. Every answer is `Cache-Control: no-store`.", "operationId": "post_spaces_ns_name_info_lfs_objects_batch", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The batch, as `git-lfs` sends it, at most 1 MiB. An upload batch to a missing repository the caller may create in creates it.", "content": { "application/vnd.git-lfs+json": { "schema": { "type": "object", "required": [ "operation", "objects" ], "properties": { "hash_algo": { "type": "string", "enum": [ "sha256" ] }, "objects": { "type": "array", "items": { "type": "object", "required": [ "oid", "size" ], "properties": { "oid": { "type": "string", "description": "The file's SHA-256, lowercase hex." }, "size": { "type": "integer" } } }, "description": "At most 1,000." }, "operation": { "type": "string", "enum": [ "upload", "download" ] }, "transfers": { "type": "array", "items": { "type": "string" }, "description": "Uploads offering `xet` answer `xet`; others get the object error `501` naming `git-xet`. Downloads are `basic`." } } } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_datasets_ns_name_info_lfs_objects_batch_200" }, "400": { "$ref": "#/components/responses/post_api_datasets_ns_name_paths_info_rev_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "408": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_408" }, "409": { "$ref": "#/components/responses/post_datasets_ns_name_info_lfs_objects_batch_409" }, "413": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_413" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, { "accessTokenBasic": [] }, {} ] } }, "/spaces/{ns}/{name}/info/lfs/objects/verify": { "post": { "tags": [ "lfs" ], "summary": "Git LFS verify", "description": "Under every Git URL, `{name}` with or without `.git`, unprefixed (whatever the labels) or under `/datasets`, `/spaces` and `/kernels`. A `401` carries `WWW-Authenticate` and `LFS-Authenticate: Basic realm=\"openxet\"`, so `git-lfs` asks its credential helpers. Every answer is `Cache-Control: no-store`.", "operationId": "post_spaces_ns_name_info_lfs_objects_verify", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The object an upload sent.", "content": { "application/vnd.git-lfs+json": { "schema": { "type": "object", "required": [ "oid", "size" ], "properties": { "oid": { "type": "string", "description": "The file's SHA-256, lowercase hex." }, "size": { "type": "integer" } } } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_datasets_ns_name_info_lfs_objects_verify_200" }, "400": { "$ref": "#/components/responses/post_api_datasets_ns_name_paths_info_rev_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/post_datasets_ns_name_info_lfs_objects_verify_404" }, "408": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_408" }, "413": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_413" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, { "accessTokenBasic": [] }, {} ] } }, "/spaces/{ns}/{name}/info/lfs/xet-read-token": { "get": { "tags": [ "lfs" ], "summary": "CAS read token", "description": "A CAS token scoped to the repository and the operation, living `hub.token_ttl`. A revision in the path is accepted and ignored. To refresh, repeat the request.", "operationId": "get_spaces_ns_name_info_lfs_xet_read_token", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_xet_read_token_rev_200" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, { "accessTokenBasic": [] }, {} ] } }, "/spaces/{ns}/{name}/info/lfs/xet-write-token": { "get": { "tags": [ "lfs" ], "summary": "CAS write token", "description": "A CAS token scoped to the repository and the operation, living `hub.token_ttl`. A revision in the path is accepted and ignored. To refresh, repeat the request.", "operationId": "get_spaces_ns_name_info_lfs_xet_write_token", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_xet_read_token_rev_200" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, { "accessTokenBasic": [] }, {} ] } }, "/spaces/{ns}/{name}/info/refs": { "get": { "tags": [ "git" ], "summary": "Ref advertisement", "description": "Smart HTTP's first request, for a clone, fetch or push. `{name}` may end in `.git`. The unprefixed URL sees every repository whatever its labels; `/datasets`, `/spaces` and `/kernels` see it through that label. For a push to a missing repository the caller may create in its namespace, it advertises an empty repository.", "operationId": "get_spaces_ns_name_info_refs", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "service", "in": "query", "description": "The service; a request without one is the dumb protocol's, answered `404`.", "required": true, "schema": { "type": "string", "enum": [ "git-upload-pack", "git-receive-pack" ] } }, { "name": "Git-Protocol", "in": "header", "description": "`version=2` for protocol v2.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_datasets_ns_name_info_refs_200" }, "401": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_401" }, "403": { "$ref": "#/components/responses/post_datasets_ns_name_git_upload_pack_403" }, "404": { "$ref": "#/components/responses/get_datasets_ns_name_info_refs_404" }, "500": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_500" }, "503": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_503" } }, "security": [ { "accessToken": [] }, { "accessTokenBasic": [] }, {} ] } }, "/spaces/{ns}/{name}/resolve/{rev}/": { "get": { "tags": [ "hub" ], "summary": "Download a file", "description": "A file at a revision, as `hf_hub_download` and plain HTTP clients read it; `HEAD` answers the same without a body. A file stored in Git answers inline, `Range` included. A Xet file redirects to the file gateway, with the headers `huggingface_hub` reads. The model view has no prefix; the other types are under `/datasets`, `/spaces` and `/kernels`. The path is read inside the commit's tree only, so `.`, `..`, a folder or the root name no file.", "operationId": "get_spaces_ns_name_resolve_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } }, { "name": "Range", "in": "header", "description": "One byte range: `bytes=start-end`, `bytes=start-` or `bytes=-length`.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_200" }, "206": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_206" }, "302": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_302" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_404" }, "413": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_413" }, "416": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_416" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/spaces/{ns}/{name}/resolve/{rev}/{path}": { "get": { "tags": [ "hub" ], "summary": "Download a file", "description": "A file at a revision, as `hf_hub_download` and plain HTTP clients read it; `HEAD` answers the same without a body. A file stored in Git answers inline, `Range` included. A Xet file redirects to the file gateway, with the headers `huggingface_hub` reads. The model view has no prefix; the other types are under `/datasets`, `/spaces` and `/kernels`. The path is read inside the commit's tree only, so `.`, `..`, a folder or the root name no file.", "operationId": "get_spaces_ns_name_resolve_rev_path", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "A path in the repository. It may hold `/`.", "required": true, "schema": { "type": "string" } }, { "name": "Range", "in": "header", "description": "One byte range: `bytes=start-end`, `bytes=start-` or `bytes=-length`.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_200" }, "206": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_206" }, "302": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_302" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_404" }, "413": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_413" }, "416": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_416" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/v1/capabilities/{repo}/{op}": { "get": { "tags": [ "lfs" ], "summary": "Refresh an upload's CAS token", "description": "The `href` of an LFS upload action, which `git-xet` calls to refresh its CAS token. The signature is the whole authorization: an `Authorization` header is never used, logged or echoed. The token lives `hub.token_ttl`, never past the capability's `exp`, for the repository and the pusher it was issued to. `{repo}` is the repository's id and `{op}` is `write`. Use the `href` exactly as given.", "operationId": "get_v1_capabilities_repo_op", "parameters": [ { "name": "repo", "in": "path", "description": "The repository's id, as the server's own URLs give it.", "required": true, "schema": { "type": "string" } }, { "name": "op", "in": "path", "description": "The operation the capability grants: `write`.", "required": true, "schema": { "type": "string" } }, { "name": "exp", "in": "query", "description": "When the capability expires, Unix seconds.", "required": true, "schema": { "type": "integer" } }, { "name": "sub", "in": "query", "description": "The subject it was issued to.", "required": true, "schema": { "type": "string" } }, { "name": "sig", "in": "query", "description": "The signature over the repository, the operation, the subject and `exp`.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_xet_read_token_rev_200" }, "403": { "description": "`capability_refused`: the capability is altered, presented for another repository, operation or subject, or past its `exp`; push again for a fresh one.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } }, "404": { "description": "`repo_not_found`: the repository no longer exists.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "description": "`not_ready`: the server is starting. `Retry-After: 1`.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "signedUrl": [] } ] } }, "/v1/chunks/{prefix}/{hash}": { "get": { "tags": [ "cas" ], "summary": "Global dedup query", "description": "Is the chunk with this raw hash stored in a xorb the caller may see? `{prefix}` is `default` (what `hf_xet` sends) or `default-merkledb` (what the spec names). The answer's chunk hashes are HMAC-keyed with a fresh key per answer, so it never reveals a raw chunk hash.", "operationId": "get_v1_chunks_prefix_hash", "parameters": [ { "name": "prefix", "in": "path", "description": "`default`; the dedup query also takes `default-merkledb`.", "required": true, "schema": { "type": "string" } }, { "name": "hash", "in": "path", "description": "A Xet hash, 64 lowercase hex characters.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A shard with a footer offering the xorb holding the chunk and the other xorbs of the newest shard referencing it, up to 16 MiB.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/octet-stream": { "schema": { "type": "string", "contentMediaType": "application/octet-stream" } } } }, "400": { "$ref": "#/components/responses/get_v1_chunks_prefix_hash_400" }, "401": { "$ref": "#/components/responses/get_v1_chunks_prefix_hash_401" }, "404": { "description": "`not_found`: no visible xorb offers the chunk, or `{prefix}` is not one of the two.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "429": { "description": "`dedup_busy`: every dedup slot stayed busy for 1 s. `Retry-After: 1`.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "$ref": "#/components/responses/get_v1_chunks_prefix_hash_500" }, "503": { "$ref": "#/components/responses/get_v1_chunks_prefix_hash_503" } }, "security": [ { "casToken": [] } ] } }, "/v1/files/{hash}": { "head": { "tags": [ "cas" ], "summary": "Whether a file is stored", "operationId": "head_v1_files_hash", "parameters": [ { "name": "hash", "in": "path", "description": "A Xet hash, 64 lowercase hex characters.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Registered; `Content-Length` is its size.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "$ref": "#/components/responses/get_v1_chunks_prefix_hash_400" }, "401": { "$ref": "#/components/responses/get_v1_chunks_prefix_hash_401" }, "404": { "description": "`not_found`: not registered to the caller's scope.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "$ref": "#/components/responses/get_v1_chunks_prefix_hash_500" }, "503": { "$ref": "#/components/responses/get_v1_chunks_prefix_hash_503" } }, "security": [ { "casToken": [] } ] } }, "/v1/reconstructions": { "get": { "tags": [ "cas" ], "summary": "Download plans for several files, as `xet-client` asks", "description": "The plans for several files at once, each planned whole (https://huggingface.co/docs/xet/api#6-batch-file-reconstruction). A file named twice is answered once; a file not registered to the scope is left out.", "operationId": "get_v1_reconstructions", "parameters": [ { "name": "file_id", "in": "query", "description": "A file hash; repeat it once per file.", "required": true, "schema": { "type": "array", "items": { "type": "string", "pattern": "^[0-9a-f]{64}$" } } } ], "responses": { "200": { "$ref": "#/components/responses/get_v1_reconstructions_200" }, "400": { "description": "`invalid_path`: the path holds a percent-encoded byte. `invalid_hash`: a hash is not 64 lowercase hex characters. `batch_too_large`: more than 1000 distinct files, or more than 100,000 terms.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "401": { "$ref": "#/components/responses/get_v1_chunks_prefix_hash_401" }, "413": { "description": "`answer_too_large`: the answer would hold more than an eighth of the memory budget; put fewer files in a batch.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "$ref": "#/components/responses/get_v1_chunks_prefix_hash_500" }, "503": { "$ref": "#/components/responses/get_v1_reconstructions_503" } }, "security": [ { "casToken": [] } ] }, "post": { "tags": [ "cas" ], "summary": "Download plans for several files", "description": "The plans for several files at once, each planned whole (https://huggingface.co/docs/xet/api#6-batch-file-reconstruction). A file named twice is answered once; a file not registered to the scope is left out.", "operationId": "post_v1_reconstructions", "parameters": [], "requestBody": { "description": "The files, at most 256 KiB.", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "prefix", "hash" ], "properties": { "hash": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "prefix": { "type": "string", "enum": [ "default" ] } } } } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/get_v1_reconstructions_200" }, "400": { "description": "`invalid_path`: the path holds a percent-encoded byte. `invalid_hash`: a hash is not 64 lowercase hex characters. `batch_too_large`: more than 1000 distinct files, or more than 100,000 terms. `bad_request`: the body ended before its `Content-Length`, or its transfer was malformed. `invalid_batch`: the body is not a JSON list of `{\"prefix\": \"default\", \"hash\"}` keys.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "401": { "$ref": "#/components/responses/get_v1_chunks_prefix_hash_401" }, "408": { "$ref": "#/components/responses/post_v1_reconstructions_408" }, "413": { "description": "`answer_too_large`: the answer would hold more than an eighth of the memory budget; put fewer files in a batch. `payload_too_large`: the body is over 256 KiB.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "$ref": "#/components/responses/get_v1_chunks_prefix_hash_500" }, "503": { "$ref": "#/components/responses/get_v1_reconstructions_503" } }, "security": [ { "casToken": [] } ] } }, "/v1/reconstructions/{hash}": { "get": { "tags": [ "cas" ], "summary": "Download plan for a file, v1 shape", "description": "The plan to download a file registered to the caller's scope, optionally for one `Range` (https://huggingface.co/docs/xet/api#1-get-file-reconstruction). Another scope's file reads the same as one never stored.", "operationId": "get_v1_reconstructions_hash", "parameters": [ { "name": "hash", "in": "path", "description": "A Xet hash, 64 lowercase hex characters.", "required": true, "schema": { "type": "string" } }, { "name": "Range", "in": "header", "description": "`bytes=start-end` (inclusive), `bytes=start-` or `bytes=-length`; an end past the file is clamped.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The plan.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "offset_into_first_range", "terms", "fetch_info" ], "properties": { "fetch_info": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "required": [ "range", "url", "url_range" ], "properties": { "range": { "type": "object", "description": "Chunk indices, end-exclusive.", "required": [ "start", "end" ], "properties": { "end": { "type": "integer", "minimum": 0 }, "start": { "type": "integer", "minimum": 0 } } }, "url": { "type": "string", "description": "A transfer URL signed for exactly `url_range`." }, "url_range": { "type": "object", "description": "Bytes, end-inclusive.", "required": [ "start", "end" ], "properties": { "end": { "type": "integer", "minimum": 0 }, "start": { "type": "integer", "minimum": 0 } } } } } } }, "offset_into_first_range": { "type": "integer", "minimum": 0 }, "terms": { "type": "array", "items": { "type": "object", "required": [ "hash", "unpacked_length", "range" ], "properties": { "hash": { "type": "string", "description": "The xorb's hash." }, "range": { "type": "object", "description": "Chunk indices, end-exclusive.", "required": [ "start", "end" ], "properties": { "end": { "type": "integer", "minimum": 0 }, "start": { "type": "integer", "minimum": 0 } } }, "unpacked_length": { "type": "integer", "minimum": 0 } } } } } } } } }, "400": { "$ref": "#/components/responses/get_v1_reconstructions_hash_400" }, "401": { "$ref": "#/components/responses/get_v1_chunks_prefix_hash_401" }, "404": { "$ref": "#/components/responses/get_v1_reconstructions_hash_404" }, "413": { "$ref": "#/components/responses/get_v1_reconstructions_hash_413" }, "416": { "$ref": "#/components/responses/get_v1_reconstructions_hash_416" }, "500": { "$ref": "#/components/responses/get_v1_chunks_prefix_hash_500" }, "503": { "$ref": "#/components/responses/get_v1_reconstructions_503" } }, "security": [ { "casToken": [] } ] } }, "/v1/shards": { "post": { "tags": [ "cas" ], "summary": "Register files", "description": "Parses the shard, verifies it against the stored chunk hashes of every xorb it references, stores it, then registers its files to the caller's scope. Uploading again is safe.", "operationId": "post_v1_shards", "parameters": [], "requestBody": { "description": "An upload shard (https://huggingface.co/docs/xet/shard), at most 64 MiB.", "content": { "application/octet-stream": { "schema": { "type": "string", "contentMediaType": "application/octet-stream" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_shards_200" }, "400": { "$ref": "#/components/responses/post_shards_400" }, "401": { "$ref": "#/components/responses/post_shards_401" }, "403": { "$ref": "#/components/responses/post_shards_403" }, "408": { "$ref": "#/components/responses/post_shards_408" }, "413": { "$ref": "#/components/responses/post_shards_413" }, "500": { "$ref": "#/components/responses/get_healthz_500" }, "503": { "$ref": "#/components/responses/post_shards_503" } }, "security": [ { "casToken": [] } ] } }, "/v1/telemetry": { "post": { "tags": [ "cas" ], "summary": "Accept and drop transfer statistics", "description": "`hf_xet` reports transfer statistics here. The body is read and dropped: never stored or logged.", "operationId": "post_v1_telemetry", "parameters": [], "requestBody": { "description": "Whatever the client reports; up to 64 KiB.", "content": { "application/json": { "schema": { "type": "object" } } }, "required": true }, "responses": { "204": { "description": "Accepted and dropped.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "$ref": "#/components/responses/post_v1_telemetry_400" }, "401": { "$ref": "#/components/responses/post_shards_401" }, "408": { "$ref": "#/components/responses/post_shards_408" }, "413": { "description": "`payload_too_large`: the body is over 64 KiB.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "$ref": "#/components/responses/get_healthz_500" }, "503": { "description": "`not_ready`: the server is starting. `Retry-After: 1`. `unavailable`: the index or bucket failed in a way a retry may fix.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "casToken": [] } ] } }, "/v1/transfer/files/{repo}/{file}": { "get": { "tags": [ "gateway" ], "summary": "Read a Xet file", "description": "A Xet file of a repository over plain HTTP, where `resolve` redirects and the LFS `basic` download `href` points; `HEAD` answers the same without a body. `{repo}` is the repository's id and `{file}` the file's Xet hash. A file is served only to the repository whose uploads registered it. A `401` offers `Basic` first, as `git-lfs` needs.", "operationId": "get_v1_transfer_files_repo_file", "parameters": [ { "name": "repo", "in": "path", "description": "The repository's id, as the server's own URLs give it.", "required": true, "schema": { "type": "string" } }, { "name": "file", "in": "path", "description": "A file's Xet hash, 64 lowercase hex characters.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "query", "description": "The file name for `Content-Disposition`; the Xet hash if left out.", "required": false, "schema": { "type": "string" } }, { "name": "commit", "in": "query", "description": "The commit `resolve` read the file at, repeated as `X-Repo-Commit`; informational.", "required": false, "schema": { "type": "string" } }, { "name": "Range", "in": "header", "description": "One byte range: `bytes=start-end`, `bytes=start-` or `bytes=-length`.", "required": false, "schema": { "type": "string" } }, { "name": "If-Range", "in": "header", "description": "The `ETag`: serve the range only if the file is unchanged.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The file.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "ETag": { "schema": { "type": "string" }, "description": "The file's SHA-256 as this repository registered it, quoted; else its Xet hash." }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Xet-Hash": { "schema": { "type": "string" }, "description": "The file's Xet hash." } }, "content": { "application/octet-stream": { "schema": { "type": "string", "contentMediaType": "application/octet-stream" } } } }, "206": { "description": "The requested range.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "Content-Range": { "schema": { "type": "string" }, "description": "`bytes start-end/size`." }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/octet-stream": { "schema": { "type": "string", "contentMediaType": "application/octet-stream" } } } }, "400": { "description": "`bad_request`: `{file}` is not a Xet hash, or `commit` is not a commit id.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "description": "`repo_not_found`: no such repository, or one the caller may not read; the two answer alike. `file_not_stored`: the repository never registered the file. `X-Error-Code: EntryNotFound`.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } }, "413": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_413" }, "416": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_416" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "description": "`not_ready`: the server is starting. `Retry-After: 1`. `authorizer_unavailable`: the authorizer could not decide. `unavailable`: the index or the bucket failed. `Retry-After: 1`. `memory_busy`: the memory budget stayed full. `Retry-After: 1`.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "accessToken": [] }, { "accessTokenBasic": [] }, {} ] } }, "/v1/transfer/xorbs/{hash}": { "get": { "tags": [ "cas" ], "summary": "Bytes of a xorb", "description": "The data URLs a reconstruction hands out. The signed query is the credential: a URL is valid for one xorb, one byte range and until its `exp`, and only with exactly `Range: bytes={start}-{end}`. Use the URL exactly as returned; its query is never logged.", "operationId": "get_v1_transfer_xorbs_hash", "parameters": [ { "name": "hash", "in": "path", "description": "A Xet hash, 64 lowercase hex characters.", "required": true, "schema": { "type": "string" } }, { "name": "range", "in": "query", "description": "`{start}-{end}`: the signed byte range, inclusive.", "required": true, "schema": { "type": "string" } }, { "name": "exp", "in": "query", "description": "When the URL expires, in Unix seconds.", "required": true, "schema": { "type": "string" } }, { "name": "sig", "in": "query", "description": "The signature over the xorb, the range and `exp`.", "required": true, "schema": { "type": "string" } }, { "name": "Range", "in": "header", "description": "Exactly `bytes={start}-{end}`, the signed range.", "required": true, "schema": { "type": "string" } } ], "responses": { "206": { "description": "Exactly the signed bytes, with `Content-Range: bytes {start}-{end}/{size}`.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/octet-stream": { "schema": { "type": "string", "contentMediaType": "application/octet-stream" } } } }, "400": { "description": "`invalid_transfer_url`: the query is missing `range`, `exp` or `sig`, or doesn't parse. `bad_range`: no `Range` header, or more than one. `invalid_path`, `invalid_hash`: the path is not a xorb hash.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "403": { "description": "`forbidden`: the signature doesn't match, the URL has expired or lies further ahead than this server allows, or `Range` isn't the signed range. Ask for a fresh reconstruction.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "$ref": "#/components/responses/get_v1_chunks_prefix_hash_500" }, "503": { "description": "`not_ready`: the server is starting. `Retry-After: 1`. `unavailable`: the bucket failed in a way a retry may fix.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "signedUrl": [] } ] }, "head": { "tags": [ "cas" ], "summary": "Refused: use GET", "description": "A transfer URL serves `GET` only; `HEAD` is always refused.", "operationId": "head_v1_transfer_xorbs_hash", "parameters": [ { "name": "hash", "in": "path", "description": "A Xet hash, 64 lowercase hex characters.", "required": true, "schema": { "type": "string" } } ], "responses": { "405": { "description": "`method_not_allowed`. `Allow: GET`.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "$ref": "#/components/responses/get_v1_chunks_prefix_hash_500" }, "503": { "description": "`not_ready`: the server is starting. `Retry-After: 1`.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [] } }, "/v1/xorbs/{prefix}/{hash}": { "post": { "tags": [ "cas" ], "summary": "Upload a xorb", "description": "One xorb, its chunks serialized as stock clients send them, with or without a footer (https://huggingface.co/docs/xet/xorb). It is validated, and its computed hash must be `{hash}`. Uploading again is safe. `{prefix}` is `default`.", "operationId": "post_v1_xorbs_prefix_hash", "parameters": [ { "name": "prefix", "in": "path", "description": "`default`; the dedup query also takes `default-merkledb`.", "required": true, "schema": { "type": "string" } }, { "name": "hash", "in": "path", "description": "A Xet hash, 64 lowercase hex characters.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The serialized xorb, at most 64.5 MiB.", "content": { "application/octet-stream": { "schema": { "type": "string", "contentMediaType": "application/octet-stream" } } }, "required": true }, "responses": { "200": { "description": "Stored.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "was_inserted" ], "properties": { "was_inserted": { "type": "boolean", "description": "Whether the xorb was new to the caller's tenant." } } } } } }, "400": { "description": "`invalid_path`: the path holds a percent-encoded byte. `invalid_hash`: a hash is not 64 lowercase hex characters. `bad_request`: the body ended before its `Content-Length`, or its transfer was malformed. `xorb_hash_mismatch`, `xorb_malformed`, `xorb_empty`, `xorb_too_many_chunks`, `xorb_chunk_empty`, `xorb_chunk_too_long`, `xorb_chunk_too_short`, `xorb_truncated`, `xorb_trailing_bytes`: the body is not a valid xorb with this hash; the message names the rule and the chunk. Final.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "401": { "$ref": "#/components/responses/get_v1_chunks_prefix_hash_401" }, "403": { "description": "`insufficient_scope`: a read token on a route that writes.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "404": { "description": "`not_found`: `{prefix}` is not `default`.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "408": { "$ref": "#/components/responses/post_v1_reconstructions_408" }, "413": { "description": "`xorb_too_large`: the body is over 64.5 MiB. `exceeds_memory_budget`: the upload is larger than the server's whole memory budget.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "$ref": "#/components/responses/get_v1_chunks_prefix_hash_500" }, "503": { "description": "`not_ready`: the server is starting. `Retry-After: 1`. `unavailable`: the index or bucket failed in a way a retry may fix. `memory_busy`: the memory budget stayed full for 120 s. `Retry-After: 1`.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } } }, "security": [ { "casToken": [] } ] }, "head": { "tags": [ "cas" ], "summary": "Whether a xorb is stored", "operationId": "head_v1_xorbs_prefix_hash", "parameters": [ { "name": "prefix", "in": "path", "description": "`default`; the dedup query also takes `default-merkledb`.", "required": true, "schema": { "type": "string" } }, { "name": "hash", "in": "path", "description": "A Xet hash, 64 lowercase hex characters.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Stored; `Content-Length` is its size.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "400": { "$ref": "#/components/responses/get_v1_chunks_prefix_hash_400" }, "401": { "$ref": "#/components/responses/get_v1_chunks_prefix_hash_401" }, "404": { "description": "`xorb_not_found`: not visible to the caller's tenant. `not_found`: `{prefix}` is not `default`.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "500": { "$ref": "#/components/responses/get_v1_chunks_prefix_hash_500" }, "503": { "$ref": "#/components/responses/get_v1_chunks_prefix_hash_503" } }, "security": [ { "casToken": [] } ] } }, "/v2/reconstructions/{hash}": { "get": { "tags": [ "cas" ], "summary": "Download plan for a file", "description": "The plan to download a file registered to the caller's scope, optionally for one `Range` (https://huggingface.co/docs/xet/api#1-get-file-reconstruction). Another scope's file reads the same as one never stored.", "operationId": "get_v2_reconstructions_hash", "parameters": [ { "name": "hash", "in": "path", "description": "A Xet hash, 64 lowercase hex characters.", "required": true, "schema": { "type": "string" } }, { "name": "Range", "in": "header", "description": "`bytes=start-end` (inclusive), `bytes=start-` or `bytes=-length`; an end past the file is clamped.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The plan.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "offset_into_first_range", "terms", "xorbs" ], "properties": { "offset_into_first_range": { "type": "integer", "minimum": 0 }, "terms": { "type": "array", "items": { "type": "object", "required": [ "hash", "unpacked_length", "range" ], "properties": { "hash": { "type": "string", "description": "The xorb's hash." }, "range": { "type": "object", "description": "Chunk indices, end-exclusive.", "required": [ "start", "end" ], "properties": { "end": { "type": "integer", "minimum": 0 }, "start": { "type": "integer", "minimum": 0 } } }, "unpacked_length": { "type": "integer", "minimum": 0 } } } }, "xorbs": { "type": "object", "description": "Fetches by xorb hash.", "additionalProperties": { "type": "array", "items": { "type": "object", "required": [ "url", "ranges" ], "properties": { "ranges": { "type": "array", "items": { "type": "object", "required": [ "chunks", "bytes" ], "properties": { "bytes": { "type": "object", "description": "Bytes, end-inclusive.", "required": [ "start", "end" ], "properties": { "end": { "type": "integer", "minimum": 0 }, "start": { "type": "integer", "minimum": 0 } } }, "chunks": { "type": "object", "description": "Chunk indices, end-exclusive.", "required": [ "start", "end" ], "properties": { "end": { "type": "integer", "minimum": 0 }, "start": { "type": "integer", "minimum": 0 } } } } } }, "url": { "type": "string", "description": "A signed transfer URL." } } } } } } } } } }, "400": { "$ref": "#/components/responses/get_v1_reconstructions_hash_400" }, "401": { "$ref": "#/components/responses/get_v1_chunks_prefix_hash_401" }, "404": { "$ref": "#/components/responses/get_v1_reconstructions_hash_404" }, "413": { "$ref": "#/components/responses/get_v1_reconstructions_hash_413" }, "416": { "$ref": "#/components/responses/get_v1_reconstructions_hash_416" }, "500": { "$ref": "#/components/responses/get_v1_chunks_prefix_hash_500" }, "503": { "$ref": "#/components/responses/get_v1_reconstructions_503" } }, "security": [ { "casToken": [] } ] } }, "/v2/shards": { "post": { "tags": [ "cas" ], "summary": "Register files, streaming progress", "description": "The ingest of `POST /v1/shards`, preferred by `hf_xet` (https://huggingface.co/docs/xet/api#5-streaming-shard-upload). Once the body is read, every outcome is a line of the stream; the last event repeats every `cas.heartbeat_interval` while work runs, and exactly one `result` or `error` ends it. A client that disconnects doesn't stop the work.", "operationId": "post_v2_shards", "parameters": [], "requestBody": { "description": "An upload shard (https://huggingface.co/docs/xet/shard), at most 64 MiB.", "content": { "application/octet-stream": { "schema": { "type": "string", "contentMediaType": "application/octet-stream" } } }, "required": true }, "responses": { "200": { "description": "Newline-delimited JSON events, `Cache-Control: no-cache`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/x-ndjson": { "schema": { "oneOf": [ { "type": "object", "required": [ "type", "verified", "total" ], "properties": { "total": { "type": "integer", "minimum": 0 }, "type": { "type": "string", "enum": [ "validating" ] }, "verified": { "type": "integer", "minimum": 0 } } }, { "type": "object", "required": [ "type", "stage" ], "properties": { "stage": { "type": "string", "enum": [ "uploading", "syncing" ] }, "type": { "type": "string", "enum": [ "committing" ] } } }, { "type": "object", "required": [ "type", "result" ], "properties": { "result": { "type": "integer", "enum": [ 0, 1 ] }, "type": { "type": "string", "enum": [ "result" ] } } }, { "type": "object", "required": [ "type", "message", "retryable" ], "properties": { "message": { "type": "string" }, "retryable": { "type": "boolean" }, "type": { "type": "string", "enum": [ "error" ] } } } ], "description": "One event per line." } } } }, "400": { "$ref": "#/components/responses/post_v1_telemetry_400" }, "401": { "$ref": "#/components/responses/post_shards_401" }, "403": { "$ref": "#/components/responses/post_shards_403" }, "408": { "$ref": "#/components/responses/post_shards_408" }, "413": { "$ref": "#/components/responses/post_shards_413" }, "500": { "$ref": "#/components/responses/get_healthz_500" }, "503": { "$ref": "#/components/responses/post_shards_503" } }, "security": [ { "casToken": [] } ] } }, "/{ns}/{name}/git-receive-pack": { "post": { "tags": [ "git" ], "summary": "Push", "description": "One push, whose refs move only through the fenced commit transaction. The first push to a missing repository creates it when the caller may create in its namespace.", "operationId": "post_ns_name_git_receive_pack", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "Content-Encoding", "in": "header", "description": "`gzip`, as git sends a large fetch request; inflated as it arrives.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "description": "Git's request, in pkt-lines. Only this type is taken, as `git http-backend` does, so a browser can't send it without a CORS preflight.", "content": { "application/x-git-receive-pack-request": { "schema": { "type": "string", "contentMediaType": "application/x-git-receive-pack-request" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_200" }, "401": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_401" }, "403": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_403" }, "404": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_404" }, "408": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_408" }, "413": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_413" }, "415": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_415" }, "500": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_500" }, "503": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_503" } }, "security": [ { "accessToken": [] }, { "accessTokenBasic": [] }, {} ] } }, "/{ns}/{name}/git-upload-pack": { "post": { "tags": [ "git" ], "summary": "Fetch", "description": "One stateless fetch or `ls-refs` request. A want the refs don't reach is refused.", "operationId": "post_ns_name_git_upload_pack", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "Content-Encoding", "in": "header", "description": "`gzip`, as git sends a large fetch request; inflated as it arrives.", "required": false, "schema": { "type": "string" } } ], "requestBody": { "description": "Git's request, in pkt-lines. Only this type is taken, as `git http-backend` does, so a browser can't send it without a CORS preflight.", "content": { "application/x-git-upload-pack-request": { "schema": { "type": "string", "contentMediaType": "application/x-git-upload-pack-request" } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_datasets_ns_name_git_upload_pack_200" }, "401": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_401" }, "403": { "$ref": "#/components/responses/post_datasets_ns_name_git_upload_pack_403" }, "404": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_404" }, "408": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_408" }, "415": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_415" }, "429": { "$ref": "#/components/responses/post_datasets_ns_name_git_upload_pack_429" }, "500": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_500" }, "503": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_503" } }, "security": [ { "accessToken": [] }, { "accessTokenBasic": [] }, {} ] } }, "/{ns}/{name}/info/lfs/objects/batch": { "post": { "tags": [ "lfs" ], "summary": "Git LFS batch", "description": "Under every Git URL, `{name}` with or without `.git`, unprefixed (whatever the labels) or under `/datasets`, `/spaces` and `/kernels`. A `401` carries `WWW-Authenticate` and `LFS-Authenticate: Basic realm=\"openxet\"`, so `git-lfs` asks its credential helpers. Every answer is `Cache-Control: no-store`.", "operationId": "post_ns_name_info_lfs_objects_batch", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The batch, as `git-lfs` sends it, at most 1 MiB. An upload batch to a missing repository the caller may create in creates it.", "content": { "application/vnd.git-lfs+json": { "schema": { "type": "object", "required": [ "operation", "objects" ], "properties": { "hash_algo": { "type": "string", "enum": [ "sha256" ] }, "objects": { "type": "array", "items": { "type": "object", "required": [ "oid", "size" ], "properties": { "oid": { "type": "string", "description": "The file's SHA-256, lowercase hex." }, "size": { "type": "integer" } } }, "description": "At most 1,000." }, "operation": { "type": "string", "enum": [ "upload", "download" ] }, "transfers": { "type": "array", "items": { "type": "string" }, "description": "Uploads offering `xet` answer `xet`; others get the object error `501` naming `git-xet`. Downloads are `basic`." } } } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_datasets_ns_name_info_lfs_objects_batch_200" }, "400": { "$ref": "#/components/responses/post_api_datasets_ns_name_paths_info_rev_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "408": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_408" }, "409": { "$ref": "#/components/responses/post_datasets_ns_name_info_lfs_objects_batch_409" }, "413": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_413" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, { "accessTokenBasic": [] }, {} ] } }, "/{ns}/{name}/info/lfs/objects/verify": { "post": { "tags": [ "lfs" ], "summary": "Git LFS verify", "description": "Under every Git URL, `{name}` with or without `.git`, unprefixed (whatever the labels) or under `/datasets`, `/spaces` and `/kernels`. A `401` carries `WWW-Authenticate` and `LFS-Authenticate: Basic realm=\"openxet\"`, so `git-lfs` asks its credential helpers. Every answer is `Cache-Control: no-store`.", "operationId": "post_ns_name_info_lfs_objects_verify", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "The object an upload sent.", "content": { "application/vnd.git-lfs+json": { "schema": { "type": "object", "required": [ "oid", "size" ], "properties": { "oid": { "type": "string", "description": "The file's SHA-256, lowercase hex." }, "size": { "type": "integer" } } } } }, "required": true }, "responses": { "200": { "$ref": "#/components/responses/post_datasets_ns_name_info_lfs_objects_verify_200" }, "400": { "$ref": "#/components/responses/post_api_datasets_ns_name_paths_info_rev_400" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/post_datasets_ns_name_info_lfs_objects_verify_404" }, "408": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_408" }, "413": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_413" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, { "accessTokenBasic": [] }, {} ] } }, "/{ns}/{name}/info/lfs/xet-read-token": { "get": { "tags": [ "lfs" ], "summary": "CAS read token", "description": "A CAS token scoped to the repository and the operation, living `hub.token_ttl`. A revision in the path is accepted and ignored. To refresh, repeat the request.", "operationId": "get_ns_name_info_lfs_xet_read_token", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_xet_read_token_rev_200" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, { "accessTokenBasic": [] }, {} ] } }, "/{ns}/{name}/info/lfs/xet-write-token": { "get": { "tags": [ "lfs" ], "summary": "CAS write token", "description": "A CAS token scoped to the repository and the operation, living `hub.token_ttl`. A revision in the path is accepted and ignored. To refresh, repeat the request.", "operationId": "get_ns_name_info_lfs_xet_write_token", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_api_datasets_ns_name_xet_read_token_rev_200" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/post_api_datasets_ns_name_branch_branch_403" }, "404": { "$ref": "#/components/responses/delete_api_datasets_ns_name_branch_branch_404" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_api_datasets_503" } }, "security": [ { "accessToken": [] }, { "accessTokenBasic": [] }, {} ] } }, "/{ns}/{name}/info/refs": { "get": { "tags": [ "git" ], "summary": "Ref advertisement", "description": "Smart HTTP's first request, for a clone, fetch or push. `{name}` may end in `.git`. The unprefixed URL sees every repository whatever its labels; `/datasets`, `/spaces` and `/kernels` see it through that label. For a push to a missing repository the caller may create in its namespace, it advertises an empty repository.", "operationId": "get_ns_name_info_refs", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "service", "in": "query", "description": "The service; a request without one is the dumb protocol's, answered `404`.", "required": true, "schema": { "type": "string", "enum": [ "git-upload-pack", "git-receive-pack" ] } }, { "name": "Git-Protocol", "in": "header", "description": "`version=2` for protocol v2.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_datasets_ns_name_info_refs_200" }, "401": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_401" }, "403": { "$ref": "#/components/responses/post_datasets_ns_name_git_upload_pack_403" }, "404": { "$ref": "#/components/responses/get_datasets_ns_name_info_refs_404" }, "500": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_500" }, "503": { "$ref": "#/components/responses/post_datasets_ns_name_git_receive_pack_503" } }, "security": [ { "accessToken": [] }, { "accessTokenBasic": [] }, {} ] } }, "/{ns}/{name}/resolve/{rev}/": { "get": { "tags": [ "hub" ], "summary": "Download a file", "description": "A file at a revision, as `hf_hub_download` and plain HTTP clients read it; `HEAD` answers the same without a body. A file stored in Git answers inline, `Range` included. A Xet file redirects to the file gateway, with the headers `huggingface_hub` reads. The model view has no prefix; the other types are under `/datasets`, `/spaces` and `/kernels`. The path is read inside the commit's tree only, so `.`, `..`, a folder or the root name no file.", "operationId": "get_ns_name_resolve_rev", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } }, { "name": "Range", "in": "header", "description": "One byte range: `bytes=start-end`, `bytes=start-` or `bytes=-length`.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_200" }, "206": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_206" }, "302": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_302" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_404" }, "413": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_413" }, "416": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_416" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_503" } }, "security": [ { "accessToken": [] }, {} ] } }, "/{ns}/{name}/resolve/{rev}/{path}": { "get": { "tags": [ "hub" ], "summary": "Download a file", "description": "A file at a revision, as `hf_hub_download` and plain HTTP clients read it; `HEAD` answers the same without a body. A file stored in Git answers inline, `Range` included. A Xet file redirects to the file gateway, with the headers `huggingface_hub` reads. The model view has no prefix; the other types are under `/datasets`, `/spaces` and `/kernels`. The path is read inside the commit's tree only, so `.`, `..`, a folder or the root name no file.", "operationId": "get_ns_name_resolve_rev_path", "parameters": [ { "name": "ns", "in": "path", "description": "The repository's namespace: a user or an organization.", "required": true, "schema": { "type": "string" } }, { "name": "name", "in": "path", "description": "The repository's name. Under a Git URL it may end in `.git`.", "required": true, "schema": { "type": "string" } }, { "name": "rev", "in": "path", "description": "A revision: a branch, a tag or a commit id.", "required": true, "schema": { "type": "string" } }, { "name": "path", "in": "path", "description": "A path in the repository. It may hold `/`.", "required": true, "schema": { "type": "string" } }, { "name": "Range", "in": "header", "description": "One byte range: `bytes=start-end`, `bytes=start-` or `bytes=-length`.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_200" }, "206": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_206" }, "302": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_302" }, "401": { "$ref": "#/components/responses/get_api_datasets_401" }, "403": { "$ref": "#/components/responses/get_api_datasets_403" }, "404": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_404" }, "413": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_413" }, "416": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_416" }, "500": { "$ref": "#/components/responses/get_api_datasets_500" }, "503": { "$ref": "#/components/responses/get_datasets_ns_name_resolve_rev_503" } }, "security": [ { "accessToken": [] }, {} ] } } }, "components": { "schemas": { "ErrorBody": { "type": "object", "description": "Every error answer's body.", "required": [ "schema", "code", "message", "hint" ], "properties": { "code": { "type": "string", "description": "Stable snake case, for scripts and agents." }, "hint": { "type": "string", "description": "What to do next." }, "message": { "type": "string", "description": "What happened." }, "schema": { "type": "string", "enum": [ "openxet.error.v1" ] } } }, "GitErrorText": { "type": "string", "description": "A Git route's error: the message, then the hint, a line each, which git prints as `remote:` lines. `X-Error-Message` holds the message." }, "HubErrorBody": { "allOf": [ { "$ref": "#/components/schemas/ErrorBody" }, { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } } ], "description": "A Hub route's error body: the error body with huggingface.co's `error` field, which holds the message." } }, "responses": { "delete_api_datasets_ns_name_branch_branch_200": { "description": "Deleted.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean", "enum": [ true ] } } } } } }, "delete_api_datasets_ns_name_branch_branch_400": { "description": "`invalid_write`: a bad ref name, or a delete of `main`.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } }, "delete_api_datasets_ns_name_branch_branch_404": { "description": "`repo_not_found`: no such repository, or one the caller may not read; the two answer alike. `wrong_label`: the caller may read the repository, but it lacks the label of the route's type.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } }, "delete_api_datasets_ns_name_tag_rev_200": { "description": "Deleted.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "get_api_agent_harnesses_401": { "description": "`missing_credential`: no credential, and what was asked needs one. `invalid_credential`: the token is unknown, malformed or expired.", "headers": { "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } }, "get_api_agent_harnesses_403": { "description": "`cas_credential`: a CAS token, which only the CAS routes take.", "headers": { "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } }, "get_api_agent_harnesses_500": { "description": "`internal`: a server-side failure, logged under the `X-Request-Id`.", "headers": { "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "get_api_agent_harnesses_501": { "description": "`not_implemented`: OpenXet doesn't implement this Hub endpoint; the message names it.", "headers": { "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } }, "get_api_agent_harnesses_503": { "description": "`not_ready`: the server is starting. `Retry-After: 1`. `authorizer_unavailable`: the authorizer could not decide. `unavailable`: the index or the bucket failed. `Retry-After: 1`.", "headers": { "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "get_api_datasets_200": { "description": "A page of repositories; it may be short, even empty, and still link the next.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "Link": { "schema": { "type": "string" }, "description": "`<…>; rel=\"next\"` while more follow: the next page's URL, to follow as it is." }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "_id", "id", "author", "private", "createdAt", "labels" ], "properties": { "_id": { "type": "string" }, "author": { "type": "string", "description": "The namespace." }, "config": { "type": "object", "description": "Models only." }, "createdAt": { "type": "string", "format": "date-time" }, "disabled": { "type": "boolean" }, "downloads": { "type": "integer" }, "gated": { "type": "boolean" }, "id": { "type": "string", "description": "`{namespace}/{name}`." }, "labels": { "type": "array", "items": { "type": "string" }, "description": "OpenXet's labels (ADR 0010)." }, "likes": { "type": "integer" }, "modelId": { "type": "string", "description": "Models only." }, "private": { "type": "boolean" }, "spaces": { "type": "array", "items": { "type": "string" }, "description": "Models only." }, "tags": { "type": "array", "items": { "type": "string" } } } } } } } }, "get_api_datasets_400": { "description": "`bad_request`: `limit` is not a positive whole number, or `cursor` is not one this server issued.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } }, "get_api_datasets_401": { "description": "`missing_credential`: no credential, and what was asked needs one. `invalid_credential`: the token is unknown, malformed or expired.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } }, "get_api_datasets_403": { "description": "`cas_credential`: a CAS token, which only the CAS routes take.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } }, "get_api_datasets_500": { "description": "`internal`: a server-side failure, logged under the `X-Request-Id`.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "get_api_datasets_501": { "description": "`not_implemented`: a filter or sort other than `author`.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } }, "get_api_datasets_503": { "description": "`not_ready`: the server is starting. `Retry-After: 1`. `authorizer_unavailable`: the authorizer could not decide. `unavailable`: the index or the bucket failed. `Retry-After: 1`.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "get_api_datasets_ns_name_200": { "description": "The repository.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "_id", "id", "author", "private", "createdAt", "labels" ], "properties": { "_id": { "type": "string" }, "author": { "type": "string", "description": "The namespace." }, "config": { "type": "object", "description": "Models only." }, "createdAt": { "type": "string", "format": "date-time" }, "disabled": { "type": "boolean" }, "downloads": { "type": "integer" }, "gated": { "type": "boolean" }, "id": { "type": "string", "description": "`{namespace}/{name}`." }, "labels": { "type": "array", "items": { "type": "string" }, "description": "OpenXet's labels (ADR 0010)." }, "lastModified": { "type": "string", "format": "date-time" }, "likes": { "type": "integer" }, "modelId": { "type": "string", "description": "Models only." }, "private": { "type": "boolean" }, "sha": { "type": "string", "description": "The revision's commit." }, "siblings": { "type": "array", "items": { "type": "object", "required": [ "rfilename" ], "properties": { "blobId": { "type": "string", "description": "With `blobs`." }, "lfs": { "type": "object", "description": "With `blobs`, for an LFS file.", "properties": { "pointerSize": { "type": "integer" }, "sha256": { "type": "string" }, "size": { "type": "integer" } } }, "rfilename": { "type": "string", "description": "The file's path." }, "size": { "type": "integer", "description": "With `blobs`." } } } }, "spaces": { "type": "array", "items": { "type": "string" }, "description": "Models only." }, "tags": { "type": "array", "items": { "type": "string" } } } } } } }, "get_api_datasets_ns_name_404": { "description": "`repo_not_found`: no such repository, or one the caller may not read; the two answer alike. `wrong_label`: the caller may read the repository, but it lacks the label of the route's type. `revision_not_found`: the revision is no branch or tag, nor a commit one contains. `X-Error-Code: RevisionNotFound`.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } }, "get_api_datasets_ns_name_commits_rev_200": { "description": "A page of commits.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "Link": { "schema": { "type": "string" }, "description": "`<…>; rel=\"next\"` while more follow: the next page's URL, to follow as it is." }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Total-Count": { "schema": { "type": "string" }, "description": "On the first page, the number of commits, when it is counted within `git.reachability`'s budget." } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "id", "title", "message", "authors", "date" ], "properties": { "authors": { "type": "array", "items": { "type": "object", "properties": { "avatar": { "type": "null" }, "user": { "type": "string" } } } }, "date": { "type": "string", "format": "date-time" }, "id": { "type": "string" }, "message": { "type": "string" }, "title": { "type": "string" } } } } } } }, "get_api_datasets_ns_name_discussions_501": { "description": "`not_implemented`: OpenXet doesn't implement this Hub endpoint; the message names it.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } }, "get_api_datasets_ns_name_refs_200": { "description": "The refs.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "tags", "branches", "converts" ], "properties": { "branches": { "type": "array", "items": { "type": "object", "required": [ "name", "ref", "targetCommit" ], "properties": { "name": { "type": "string" }, "ref": { "type": "string", "description": "The full ref name." }, "targetCommit": { "type": "string", "description": "What the ref names: for an annotated tag, the tag object." } } } }, "converts": { "type": "array" }, "pullRequests": { "type": "array", "items": { "type": "object", "required": [ "name", "ref", "targetCommit" ], "properties": { "name": { "type": "string" }, "ref": { "type": "string", "description": "The full ref name." }, "targetCommit": { "type": "string", "description": "What the ref names: for an annotated tag, the tag object." } } } }, "tags": { "type": "array", "items": { "type": "object", "required": [ "name", "ref", "targetCommit" ], "properties": { "name": { "type": "string" }, "ref": { "type": "string", "description": "The full ref name." }, "targetCommit": { "type": "string", "description": "What the ref names: for an annotated tag, the tag object." } } } } } } } } }, "get_api_datasets_ns_name_tree_rev_200": { "description": "A page of entries.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "Link": { "schema": { "type": "string" }, "description": "`<…>; rel=\"next\"` while more follow: the next page's URL, to follow as it is." }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "type", "oid", "size", "path" ], "properties": { "lastCommit": { "type": "object", "description": "With `expand`.", "properties": { "date": { "type": "string", "format": "date-time" }, "id": { "type": "string" }, "title": { "type": "string" } } }, "lfs": { "type": "object", "description": "For an LFS file.", "properties": { "oid": { "type": "string", "description": "The file's SHA-256." }, "pointerSize": { "type": "integer" }, "size": { "type": "integer" } } }, "oid": { "type": "string", "description": "The Git object id." }, "path": { "type": "string" }, "securityFileStatus": { "type": "object", "description": "With `expand`; OpenXet runs no scans, so each is `unscanned`.", "properties": { "avScan": { "type": "object", "properties": { "status": { "type": "string" } } }, "pickleImportScan": { "type": "object", "properties": { "status": { "type": "string" } } }, "protectAiScan": { "type": "object", "properties": { "status": { "type": "string" } } }, "status": { "type": "string" }, "virusTotalScan": { "type": "object", "properties": { "status": { "type": "string" } } } } }, "size": { "type": "integer", "description": "An LFS file's own size." }, "type": { "type": "string", "enum": [ "file", "directory" ] }, "xetHash": { "type": "string", "description": "For an LFS file this repository registered: its Xet hash." } } } } } } }, "get_api_datasets_ns_name_tree_rev_404": { "description": "`repo_not_found`: no such repository, or one the caller may not read; the two answer alike. `wrong_label`: the caller may read the repository, but it lacks the label of the route's type. `revision_not_found`: the revision is no branch or tag, nor a commit one contains. `X-Error-Code: RevisionNotFound`. `entry_not_found`: the path names nothing at the revision. `X-Error-Code: EntryNotFound`, `X-Repo-Commit`.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } }, "get_api_datasets_ns_name_xet_read_token_rev_200": { "description": "The token, its expiry and the CAS URL, also in the `X-Xet-*` headers.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Xet-Access-Token": { "schema": { "type": "string" }, "description": "The CAS token." }, "X-Xet-Cas-Url": { "schema": { "type": "string" }, "description": "The CAS URL." }, "X-Xet-Token-Expiration": { "schema": { "type": "string" }, "description": "The token's expiry, Unix seconds." } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "accessToken", "exp", "casUrl" ], "properties": { "accessToken": { "type": "string", "description": "The CAS token." }, "casUrl": { "type": "string", "description": "The CAS to use it with." }, "exp": { "type": "integer", "description": "Its expiry, Unix seconds." } } } } } }, "get_api_openxet_v1_repos_ns_name_labels_200": { "description": "The repository's labels.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "schema", "repo", "labels" ], "properties": { "labels": { "type": "array", "items": { "type": "string" } }, "repo": { "type": "string", "description": "`{namespace}/{name}`." }, "schema": { "type": "string", "enum": [ "openxet.labels.v1" ] } } } } } }, "get_api_openxet_v1_repos_ns_name_labels_404": { "description": "`repo_not_found`: no such repository, or one the caller may not read; the two answer alike.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } }, "get_datasets_ns_name_info_refs_200": { "description": "The advertisement, in pkt-lines, typed after the service.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/x-git-upload-pack-advertisement": { "schema": { "type": "string", "contentMediaType": "application/x-git-upload-pack-advertisement" } }, "application/x-git-receive-pack-advertisement": { "schema": { "type": "string", "contentMediaType": "application/x-git-receive-pack-advertisement" } } } }, "get_datasets_ns_name_info_refs_404": { "description": "`repo_not_found`: no such repository, or one the caller may not read; the two answer alike. `wrong_label`: the caller may read the repository, but it lacks the label of the route's type. `dumb_http_not_served`: no `service`; only smart HTTP is served.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/GitErrorText" } } } }, "get_datasets_ns_name_resolve_rev_200": { "description": "The file, stored in Git.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "ETag": { "schema": { "type": "string" }, "description": "The blob's id." }, "X-Repo-Commit": { "schema": { "type": "string" }, "description": "The commit the revision resolved to." }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/octet-stream": { "schema": { "type": "string", "contentMediaType": "application/octet-stream" } } } }, "get_datasets_ns_name_resolve_rev_206": { "description": "The requested range of a file stored in Git.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "Content-Range": { "schema": { "type": "string" }, "description": "`bytes start-end/size`." }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/octet-stream": { "schema": { "type": "string", "contentMediaType": "application/octet-stream" } } } }, "get_datasets_ns_name_resolve_rev_302": { "description": "A Xet file: read it from the gateway or the CAS.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "Link": { "schema": { "type": "string" }, "description": "The `xet-auth` token route and the `xet-reconstruction-info` CAS URL." }, "Location": { "schema": { "type": "string" }, "description": "The file gateway URL of the file." }, "X-Linked-ETag": { "schema": { "type": "string" }, "description": "The file's SHA-256, quoted." }, "X-Linked-Size": { "schema": { "type": "string" }, "description": "The file's size." }, "X-Repo-Commit": { "schema": { "type": "string" }, "description": "The commit the revision resolved to." }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" }, "X-Xet-Hash": { "schema": { "type": "string" }, "description": "The file's Xet hash." } } }, "get_datasets_ns_name_resolve_rev_404": { "description": "`repo_not_found`: no such repository, or one the caller may not read; the two answer alike. `wrong_label`: the caller may read the repository, but it lacks the label of the route's type. `revision_not_found`: the revision is no branch or tag, nor a commit one contains. `X-Error-Code: RevisionNotFound`. `entry_not_found`: the path names no file, with `X-Repo-Commit`. `lfs_object_missing`: the path holds an LFS pointer whose bytes were never uploaded here. Both `X-Error-Code: EntryNotFound`.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } }, "get_datasets_ns_name_resolve_rev_413": { "description": "`answer_too_large`: one read would hold more than an answer's share of the memory budget; ask by range.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } }, "get_datasets_ns_name_resolve_rev_416": { "description": "The range starts past the end of the file. No body.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "Content-Range": { "schema": { "type": "string" }, "description": "`bytes */{size}`." }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } } }, "get_datasets_ns_name_resolve_rev_503": { "description": "`not_ready`: the server is starting. `Retry-After: 1`. `authorizer_unavailable`: the authorizer could not decide. `unavailable`: the index or the bucket failed. `Retry-After: 1`. `blob_too_large`: a Git blob too large to buffer; it won't fit later either. `memory_busy`: the memory budget stayed full. `busy`: too many reads at once.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "get_healthz_500": { "description": "`internal`: a server-side failure, logged under the `X-Request-Id`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "get_healthz_503": { "description": "`not_ready`: the server is starting. `Retry-After: 1`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "get_v1_chunks_prefix_hash_400": { "description": "`invalid_path`: the path holds a percent-encoded byte. `invalid_hash`: a hash is not 64 lowercase hex characters.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "get_v1_chunks_prefix_hash_401": { "description": "`missing_credential`, `invalid_credential`, `expired_credential`: `WWW-Authenticate` names the problem.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "get_v1_chunks_prefix_hash_500": { "description": "`internal`: a server-side failure, logged under the `X-Request-Id`.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "get_v1_chunks_prefix_hash_503": { "description": "`not_ready`: the server is starting. `Retry-After: 1`. `unavailable`: the index or bucket failed in a way a retry may fix.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "get_v1_reconstructions_200": { "description": "The plans.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "files", "fetch_info" ], "properties": { "fetch_info": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "object", "required": [ "range", "url", "url_range" ], "properties": { "range": { "type": "object", "description": "Chunk indices, end-exclusive.", "required": [ "start", "end" ], "properties": { "end": { "type": "integer", "minimum": 0 }, "start": { "type": "integer", "minimum": 0 } } }, "url": { "type": "string", "description": "A transfer URL signed for exactly `url_range`." }, "url_range": { "type": "object", "description": "Bytes, end-inclusive.", "required": [ "start", "end" ], "properties": { "end": { "type": "integer", "minimum": 0 }, "start": { "type": "integer", "minimum": 0 } } } } } } }, "files": { "type": "object", "description": "Terms by file hash.", "additionalProperties": { "type": "array", "items": { "type": "object", "required": [ "hash", "unpacked_length", "range" ], "properties": { "hash": { "type": "string", "description": "The xorb's hash." }, "range": { "type": "object", "description": "Chunk indices, end-exclusive.", "required": [ "start", "end" ], "properties": { "end": { "type": "integer", "minimum": 0 }, "start": { "type": "integer", "minimum": 0 } } }, "unpacked_length": { "type": "integer", "minimum": 0 } } } } } } } } } }, "get_v1_reconstructions_503": { "description": "`not_ready`: the server is starting. `Retry-After: 1`. `unavailable`: the index or bucket failed in a way a retry may fix. `memory_busy`: the memory budget stayed full for 5 s. `Retry-After: 1`.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "get_v1_reconstructions_hash_400": { "description": "`invalid_path`: the path holds a percent-encoded byte. `invalid_hash`: a hash is not 64 lowercase hex characters. `invalid_range`: `Range` is not one byte range.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "get_v1_reconstructions_hash_404": { "description": "`not_found`: no file with this hash is registered to the caller's scope.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "get_v1_reconstructions_hash_413": { "description": "`answer_too_large`: the answer would hold more than an eighth of the memory budget; ask by range.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "get_v1_reconstructions_hash_416": { "description": "`range_not_satisfiable`: the range starts at or past the end of the file. `Content-Range: bytes */{size}`.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "post_api_datasets_ns_name_branch_branch_200": { "description": "Created.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean", "enum": [ true ] } } } } } }, "post_api_datasets_ns_name_branch_branch_400": { "description": "`invalid_write`: a bad ref name, or a delete of `main`. `bad_request`: the body is not what the route takes.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } }, "post_api_datasets_ns_name_branch_branch_403": { "description": "`cas_credential`: a CAS token, which only the CAS routes take. `forbidden`: the caller may read the repository but not write to it.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } }, "post_api_datasets_ns_name_branch_branch_408": { "description": "`body_timeout`: the body arrived too slowly.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } }, "post_api_datasets_ns_name_branch_branch_409": { "description": "`ref_conflict`: the ref exists already, or isn't where the request read it.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } }, "post_api_datasets_ns_name_branch_branch_413": { "description": "`payload_too_large`: the body is larger than the route takes.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } }, "post_api_datasets_ns_name_branch_branch_503": { "description": "`not_ready`: the server is starting. `Retry-After: 1`. `authorizer_unavailable`: the authorizer could not decide. `unavailable`: the index or the bucket failed. `Retry-After: 1`. `busy`: too many writes in the repository at once. `Retry-After: 1`.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "post_api_datasets_ns_name_commit_rev_200": { "description": "Committed.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "success", "commitOid", "commitUrl" ], "properties": { "commitOid": { "type": "string" }, "commitUrl": { "type": "string" }, "hookOutput": { "type": "string" }, "success": { "type": "boolean", "enum": [ true ] } } } } } }, "post_api_datasets_ns_name_commit_rev_400": { "description": "`bad_request`: the body is not what the route takes. `invalid_write`: a bad path, or objects git refuses. An `lfsFile` not uploaded to this repository is `bad_request`.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } }, "post_api_datasets_ns_name_commit_rev_409": { "description": "`ref_conflict`: the branch moved while the commit was written.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } }, "post_api_datasets_ns_name_commit_rev_412": { "description": "`precondition_failed`: `parentCommit` is not the branch's tip.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } }, "post_api_datasets_ns_name_commit_rev_501": { "description": "`not_implemented`: `create_pr`.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } }, "post_api_datasets_ns_name_commit_rev_503": { "description": "`not_ready`: the server is starting. `Retry-After: 1`. `authorizer_unavailable`: the authorizer could not decide. `unavailable`: the index or the bucket failed. `Retry-After: 1`. `busy`: the commit lost its branch to concurrent writers on every attempt. `Retry-After: 1`.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "post_api_datasets_ns_name_paths_info_rev_200": { "description": "The entries.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "required": [ "type", "oid", "size", "path" ], "properties": { "lastCommit": { "type": "object", "description": "With `expand`.", "properties": { "date": { "type": "string", "format": "date-time" }, "id": { "type": "string" }, "title": { "type": "string" } } }, "lfs": { "type": "object", "description": "For an LFS file.", "properties": { "oid": { "type": "string", "description": "The file's SHA-256." }, "pointerSize": { "type": "integer" }, "size": { "type": "integer" } } }, "oid": { "type": "string", "description": "The Git object id." }, "path": { "type": "string" }, "securityFileStatus": { "type": "object", "description": "With `expand`; OpenXet runs no scans, so each is `unscanned`.", "properties": { "avScan": { "type": "object", "properties": { "status": { "type": "string" } } }, "pickleImportScan": { "type": "object", "properties": { "status": { "type": "string" } } }, "protectAiScan": { "type": "object", "properties": { "status": { "type": "string" } } }, "status": { "type": "string" }, "virusTotalScan": { "type": "object", "properties": { "status": { "type": "string" } } } } }, "size": { "type": "integer", "description": "An LFS file's own size." }, "type": { "type": "string", "enum": [ "file", "directory" ] }, "xetHash": { "type": "string", "description": "For an LFS file this repository registered: its Xet hash." } } } } } } }, "post_api_datasets_ns_name_paths_info_rev_400": { "description": "`bad_request`: the body is not what the route takes.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } }, "post_api_datasets_ns_name_preupload_rev_200": { "description": "Each file's upload mode, in request order.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "files", "commitOid" ], "properties": { "commitOid": { "type": [ "string", "null" ], "description": "The revision's commit; `null` before the first." }, "files": { "type": "array", "items": { "type": "object", "required": [ "path", "uploadMode", "shouldIgnore" ], "properties": { "path": { "type": "string" }, "shouldIgnore": { "type": "boolean" }, "uploadMode": { "type": "string", "enum": [ "lfs", "regular" ] } } } } } } } } }, "post_api_datasets_ns_name_tag_rev_200": { "description": "Tagged.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "post_datasets_ns_name_git_receive_pack_200": { "description": "Git's answer, in pkt-lines.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/x-git-receive-pack-result": { "schema": { "type": "string", "contentMediaType": "application/x-git-receive-pack-result" } } } }, "post_datasets_ns_name_git_receive_pack_401": { "description": "`missing_credential`: no credential, and what was asked needs one. `invalid_credential`: the token is unknown, malformed or expired.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/GitErrorText" } } } }, "post_datasets_ns_name_git_receive_pack_403": { "description": "`cas_credential`: a CAS token, which only the CAS routes take. `forbidden`: the caller may read the repository but not write to it.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/GitErrorText" } } } }, "post_datasets_ns_name_git_receive_pack_404": { "description": "`repo_not_found`: no such repository, or one the caller may not read; the two answer alike. `wrong_label`: the caller may read the repository, but it lacks the label of the route's type.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/GitErrorText" } } } }, "post_datasets_ns_name_git_receive_pack_408": { "description": "`body_timeout`: the body arrived too slowly.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/GitErrorText" } } } }, "post_datasets_ns_name_git_receive_pack_413": { "description": "`push_too_large`: the push is larger than `git.max_push_bytes`.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/GitErrorText" } } } }, "post_datasets_ns_name_git_receive_pack_415": { "description": "`unsupported_media_type`: not git's request type.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/GitErrorText" } } } }, "post_datasets_ns_name_git_receive_pack_500": { "description": "`internal`: a server-side failure, logged under the `X-Request-Id`.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/GitErrorText" } } } }, "post_datasets_ns_name_git_receive_pack_503": { "description": "`not_ready`: the server is starting. `Retry-After: 1`. `authorizer_unavailable`: the authorizer could not decide. `unavailable`: the index or the bucket failed. `Retry-After: 1`. `busy`: too many requests in the repository at once. `Retry-After: 1`.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } }, "text/plain": { "schema": { "$ref": "#/components/schemas/GitErrorText" } } } }, "post_datasets_ns_name_git_upload_pack_200": { "description": "Git's answer, in pkt-lines.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/x-git-upload-pack-result": { "schema": { "type": "string", "contentMediaType": "application/x-git-upload-pack-result" } } } }, "post_datasets_ns_name_git_upload_pack_403": { "description": "`cas_credential`: a CAS token, which only the CAS routes take.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/GitErrorText" } } } }, "post_datasets_ns_name_git_upload_pack_429": { "description": "`too_many_requests`: the reachability check is over its concurrency limit for the repository or the caller. `Retry-After: 1`.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "text/plain": { "schema": { "$ref": "#/components/schemas/GitErrorText" } } } }, "post_datasets_ns_name_info_lfs_objects_batch_200": { "description": "Each object with its actions or its error. An upload's `xet` actions carry a capability `href` and the CAS token in `X-Xet-*` headers; a download's `href` is the file gateway's.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/vnd.git-lfs+json": { "schema": { "type": "object", "required": [ "transfer", "objects", "hash_algo" ], "properties": { "hash_algo": { "type": "string", "enum": [ "sha256" ] }, "objects": { "type": "array", "items": { "type": "object", "required": [ "oid", "size" ], "properties": { "actions": { "type": "object", "properties": { "download": { "type": "object", "required": [ "href" ], "properties": { "expires_in": { "type": "integer" }, "header": { "type": "object", "additionalProperties": { "type": "string" } }, "href": { "type": "string" } } }, "upload": { "type": "object", "required": [ "href" ], "properties": { "expires_in": { "type": "integer" }, "header": { "type": "object", "additionalProperties": { "type": "string" } }, "href": { "type": "string" } } }, "verify": { "type": "object", "required": [ "href" ], "properties": { "expires_in": { "type": "integer" }, "header": { "type": "object", "additionalProperties": { "type": "string" } }, "href": { "type": "string" } } } } }, "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "enum": [ 404, 422, 501 ] }, "message": { "type": "string" } } }, "oid": { "type": "string" }, "size": { "type": "integer" } } } }, "transfer": { "type": "string", "enum": [ "xet", "basic" ] } } } } } }, "post_datasets_ns_name_info_lfs_objects_batch_409": { "description": "`unsupported_hash_algorithm`: `hash_algo` is not `sha256`.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } }, "post_datasets_ns_name_info_lfs_objects_verify_200": { "description": "The repository has the object.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/vnd.git-lfs+json": { "schema": { "type": "object" } } } }, "post_datasets_ns_name_info_lfs_objects_verify_404": { "description": "`repo_not_found`: no such repository, or one the caller may not read; the two answer alike. `wrong_label`: the caller may read the repository, but it lacks the label of the route's type. `object_not_uploaded`: the upload did not complete, so this is never a silent success.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } }, "post_shards_200": { "description": "Registered.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "result" ], "properties": { "result": { "type": "integer", "description": "`1` if the shard or any of its files was new to the scope, `0` if all were registered already.", "enum": [ 0, 1 ] } } } } } }, "post_shards_400": { "description": "`invalid_path`: the path holds a percent-encoded byte. `invalid_hash`: a hash is not 64 lowercase hex characters. `bad_request`: the body ended before its `Content-Length`, or its transfer was malformed. `shard_malformed`: the body doesn't parse as an upload shard. `shard_verification_failed`: it doesn't verify against the stored xorbs. `unknown_xorb`: a file references a xorb that isn't stored or visible. Final.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "post_shards_401": { "description": "`missing_credential`, `invalid_credential`, `expired_credential`: `WWW-Authenticate` names the problem.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "post_shards_403": { "description": "`insufficient_scope`: a read token on a route that writes.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "post_shards_408": { "description": "`body_timeout`: the body stalled or fell below `server.body_min_rate`. The answer closes the connection; retry.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "post_shards_413": { "description": "`shard_too_large`: the body is over 64 MiB.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "post_shards_503": { "description": "`not_ready`: the server is starting. `Retry-After: 1`. `unavailable`: the index or bucket failed in a way a retry may fix. `memory_busy`: the memory budget stayed full for 120 s. `Retry-After: 1`.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "post_v1_reconstructions_408": { "description": "`body_timeout`: the body stalled or fell below `server.body_min_rate`. The answer closes the connection; retry.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "post_v1_telemetry_400": { "description": "`invalid_path`: the path holds a percent-encoded byte. `invalid_hash`: a hash is not 64 lowercase hex characters. `bad_request`: the body ended before its `Content-Length`, or its transfer was malformed.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorBody" } } } }, "put_api_openxet_v1_repos_ns_name_labels_label_400": { "description": "`invalid_label`: the label is not a lowercase slug of `a`-`z`, `0`-`9` and `-`, 1 to 64 bytes, or the repository carries 32 already.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } }, "put_api_openxet_v1_repos_ns_name_labels_label_409": { "description": "`labels_changed`: the labels changed concurrently; nothing was changed. Retry.", "headers": { "Cache-Control": { "$ref": "#/components/headers/Cache-Control" }, "X-Error-Code": { "$ref": "#/components/headers/X-Error-Code" }, "X-Error-Message": { "$ref": "#/components/headers/X-Error-Message" }, "X-Request-Id": { "$ref": "#/components/headers/X-Request-Id" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HubErrorBody" } } } } }, "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "`no-store`: the answer depends on the caller's credential." }, "X-Error-Code": { "schema": { "type": "string" }, "description": "huggingface.co's error code (`RepoNotFound`, `RevisionNotFound`, `EntryNotFound`, …), where it defines one." }, "X-Error-Message": { "schema": { "type": "string" }, "description": "The message, as `huggingface_hub` shows it; characters a header can't carry are `?`." }, "X-Request-Id": { "schema": { "type": "string" }, "description": "The request's id, under which the server logged it. Give it to the operator." } }, "securitySchemes": { "accessToken": { "type": "http", "scheme": "bearer", "description": "An OpenXet access token, which the Hub's token routes exchange for CAS tokens." }, "accessTokenBasic": { "type": "http", "scheme": "basic", "description": "An OpenXet access token as the password; the user name is ignored." }, "casToken": { "type": "http", "scheme": "bearer", "description": "A static token or a CAS token (docs/reference/config.md#static-tokens)." }, "signedUrl": { "type": "apiKey", "in": "query", "name": "sig", "description": "A URL the server signed and handed out: its `sig` query parameter, with the others it signs, is the whole credential. Use the URL exactly as given." } } }, "tags": [ { "name": "health", "description": "Liveness and readiness probes, without a credential." }, { "name": "cas", "description": "The Xet CAS API as stock clients call it (https://huggingface.co/docs/xet/api). Routes: docs/reference/routes.md." }, { "name": "hub", "description": "The Hugging Face Hub API that `huggingface_hub`, `hf` and `huggingface.js` call. Each repository route is served under `/api/models`, `/api/datasets`, `/api/spaces` and `/api/kernels`, which see a repository through that label (ADR 0010)." }, { "name": "openxet", "description": "OpenXet's own repository API: labels." }, { "name": "git", "description": "Git smart HTTP, protocol v2 and v0. `{name}` may end in `.git`. The dumb protocol is not served." }, { "name": "lfs", "description": "The Git LFS batch API with the `xet` transfer, and the capability URLs `git-xet` refreshes its CAS token from. Routes: docs/reference/lfs.md." }, { "name": "gateway", "description": "Plain HTTP reads of a repository's Xet files, with `Range`." }, { "name": "meta", "description": "This document." } ] }