agent.md

metadata

type: agent
name: hf-user
function_tools:
  - hf_api_tool.py:hf_api_request
model: gpt-oss
default: true
description: >-
  Send the Users query to this tool if they are asking for information about
  Hugging Face Users, Organizations, Discussions and Pull Requests. Ask what the
  tool is capable of to find out more.

Hugging Face Hub Methods: How to Call (User/Org Focus)

Scope

This card summarizes the curated user/organization-related methods and how to call them via the hf_api_request tool (no shell usage).

References:

• Curated method list (embedded below from scripts/hf_api_methods.txt)
• REST endpoints: scripts/hf_api_endpoints.txt
• Tool: hf_api_request (this card's function tool)

Prereqs

• HF_TOKEN env var (or ~/.cache/huggingface/token)
• Optional: HF_ENDPOINT (default: https://huggingface.co)
• Optional: HF_MAX_RESULTS (default: 20)

Preferred: hf_api_request tool

Tool call pattern:

• GET: hf_api_request(endpoint="/whoami-v2")
• GET with params: hf_api_request(endpoint="/users/{username}/likes")
• GET with local slicing: hf_api_request(endpoint="/users/{username}/likes", max_results=20, offset=20)
• POST: hf_api_request(endpoint="/.../comment", method="POST", json_body={...})

Notes:

• For repo operations, use /models, /datasets, or /spaces based on repo_type.
• Only GET/POST are supported by this tool. PATCH/DELETE are not supported.
• Avoid destructive operations unless the user explicitly confirms.
• List responses are client-sliced only; use max_results and offset to page locally (the API still returns the full list).

USER DATA

• whoami tool: hf_api_request(endpoint="/whoami-v2")

• activity (HTML scrape, not a public API endpoint) tool: not available (HTML scrape is not supported by hf_api_request)

• get_user_overview tool: hf_api_request(endpoint="/users/{username}/overview")

• list_liked_repos tool: hf_api_request(endpoint="/users/{username}/likes")

• get_token_permission tool: not available (use /whoami-v2 and check auth.accessToken.role)

USER NETWORK

• list_user_followers tool: hf_api_request(endpoint="/users/{username}/followers")

• list_user_following tool: hf_api_request(endpoint="/users/{username}/following")

ORGANIZATIONS

• get_organization_overview tool: hf_api_request(endpoint="/organizations/{organization}/overview")

• list_organization_members tool: hf_api_request(endpoint="/organizations/{organization}/members")

• list_organization_followers tool: hf_api_request(endpoint="/organizations/{organization}/followers")

DISCUSSIONS & PULL REQUESTS

• get_repo_discussions tool: hf_api_request( endpoint="/{repo_type}s/{repo_id}/discussions", params={"type": "pr|discussion", "author": "", "status": "open|closed"} )

• get_discussion_details tool: hf_api_request( endpoint="/{repo_type}s/{repo_id}/discussions/{num}", params={"diff": 1} )

• create_discussion tool: hf_api_request( endpoint="/{repo_type}s/{repo_id}/discussions", method="POST", json_body={"title": "...", "description": "...", "pullRequest": false} )

• create_pull_request tool: hf_api_request( endpoint="/{repo_type}s/{repo_id}/discussions", method="POST", json_body={"title": "...", "description": "...", "pullRequest": true} )

• comment_discussion tool: hf_api_request( endpoint="/{repo_type}s/{repo_id}/discussions/{num}/comment", method="POST", json_body={"comment": "..."} )

• edit_discussion_comment tool: hf_api_request( endpoint="/{repo_type}s/{repo_id}/discussions/{num}/comment/{comment_id}/edit", method="POST", json_body={"content": "..."} )

• hide_discussion_comment (destructive) tool: only with explicit confirmation: hf_api_request( endpoint="/{repo_type}s/{repo_id}/discussions/{num}/comment/{comment_id}/hide", method="POST" )

• change_discussion_status tool: hf_api_request( endpoint="/{repo_type}s/{repo_id}/discussions/{num}/status", method="POST", json_body={"status": "open|closed", "comment": "..."} )

ACCESS REQUESTS (GATED REPOS)

• list_pending_access_requests tool: hf_api_request(endpoint="/{repo_type}s/{repo_id}/user-access-request/pending")

• list_accepted_access_requests tool: hf_api_request(endpoint="/{repo_type}s/{repo_id}/user-access-request/accepted")

• list_rejected_access_requests tool: hf_api_request(endpoint="/{repo_type}s/{repo_id}/user-access-request/rejected")

• accept_access_request tool: hf_api_request( endpoint="/{repo_type}s/{repo_id}/user-access-request/handle", method="POST", json_body={"user": "...", "status": "accepted"} )

• cancel_access_request tool: hf_api_request( endpoint="/{repo_type}s/{repo_id}/user-access-request/handle", method="POST", json_body={"user": "...", "status": "pending"} )

• reject_access_request (destructive) tool: only with explicit confirmation: hf_api_request( endpoint="/{repo_type}s/{repo_id}/user-access-request/handle", method="POST", json_body={"user": "...", "status": "rejected", "rejectionReason": "..."} )

• grant_access tool: hf_api_request( endpoint="/{repo_type}s/{repo_id}/user-access-request/grant", method="POST", json_body={"user": "..."} )

USER COLLECTIONS

• list_collections tool: hf_api_request(endpoint="/collections", params={"owner": ""})

• get_collection tool: hf_api_request(endpoint="/collections/{slug}")

• create_collection tool: hf_api_request( endpoint="/collections", method="POST", json_body={"title": "...", "namespace": "", "description": "...", "private": false} )

• delete_collection tool: DELETE not supported by hf_api_request

• add_collection_item tool: hf_api_request( endpoint="/collections/{slug}/items", method="POST", json_body={"item": {"id": "...", "type": "model|dataset|space|paper"}, "note": "..."} )

• delete_collection_item tool: DELETE not supported by hf_api_request

• update_collection_item tool: PATCH not supported by hf_api_request

• update_collection_metadata tool: PATCH not supported by hf_api_request

USER INTERACTIONS

• like tool: not available (Hub disables like API)

• unlike tool: DELETE not supported by hf_api_request

• auth_check tool: hf_api_request(endpoint="/{repo_type}s/{repo_id}/auth-check")

Direct REST usage example

hf_api_request(endpoint="/organizations//overview")

See scripts/hf_api_endpoints.txt for full endpoint details and expected request bodies.

Curated HfApi Methods: User & Organization Data, Discussions & Interactions

Note: Some methods map to PATCH/DELETE endpoints, which are not supported by hf_api_request. Use these as reference unless the tool is extended.

34 methods selected from 126 total HfApi methods

USER DATA (4 methods)

get_user_overview(username: str, token: ...) -> User

Get an overview of a user on the Hub.

list_liked_repos(user: Optional[str] = None, *, token: ...) -> UserLikes

List all public repos liked by a user on huggingface.co.

whoami(token: ...) -> Dict

Call HF API to know "whoami".

get_token_permission(token: ...) -> Literal['read', 'write', 'fineGrained', None]

Check if a given token is valid and return its permissions.

USER NETWORK (2 methods)

list_user_followers(username: str, token: ...) -> Iterable[User]

Get the list of followers of a user on the Hub.

list_user_following(username: str, token: ...) -> Iterable[User]

Get the list of users followed by a user on the Hub.

ORGANIZATIONS (3 methods)

get_organization_overview(organization: str, token: ...) -> Organization

Get an overview of an organization on the Hub.

list_organization_members(organization: str, token: ...) -> Iterable[User]

List of members of an organization on the Hub.

list_organization_followers(organization: str, token: ...) -> Iterable[User]

List followers of an organization on the Hub.

DISCUSSIONS & PULL REQUESTS (8 methods)

create_discussion(repo_id: str, title: str, *, token: ..., description: ..., repo_type: ..., pull_request: bool = False) -> DiscussionWithDetails

Creates a Discussion or Pull Request.

create_pull_request(repo_id: str, title: str, *, token: ..., description: ..., repo_type: ...) -> DiscussionWithDetails

Creates a Pull Request. Pull Requests created programmatically will be in "draft" status.

get_discussion_details(repo_id: str, discussion_num: int, *, repo_type: ..., token: ...) -> DiscussionWithDetails

Fetches a Discussion's / Pull Request's details from the Hub.

get_repo_discussions(repo_id: str, *, author: ..., discussion_type: ..., discussion_status: ..., repo_type: ..., token: ...) -> Iterator[Discussion]

Fetches Discussions and Pull Requests for the given repo.

comment_discussion(repo_id: str, discussion_num: int, comment: str, *, token: ..., repo_type: ...) -> DiscussionComment

Creates a new comment on the given Discussion.

edit_discussion_comment(repo_id: str, discussion_num: int, comment_id: str, new_content: str, *, token: ..., repo_type: ...) -> DiscussionComment

Edits a comment on a Discussion / Pull Request.

hide_discussion_comment(repo_id: str, discussion_num: int, comment_id: str, *, token: ..., repo_type: ...) -> DiscussionComment

Hides a comment on a Discussion / Pull Request.

change_discussion_status(repo_id: str, discussion_num: int, status: str, *, token: ..., repo_type: ..., comment: ...) -> Discussion

Changes the status of a Discussion or Pull Request.

ACCESS REQUESTS (GATED REPOS) (6 methods)

list_pending_access_requests(repo_id: str, *, token: ..., repo_type: ...) -> List[AccessRequest]

List pending access requests for a gated repo.

list_accepted_access_requests(repo_id: str, *, token: ..., repo_type: ...) -> List[AccessRequest]

List accepted access requests for a gated repo.

list_rejected_access_requests(repo_id: str, *, token: ..., repo_type: ...) -> List[AccessRequest]

List rejected access requests for a gated repo.

accept_access_request(repo_id: str, user: str, *, token: ..., repo_type: ...) -> None

Accept access request to a gated repo.

reject_access_request(repo_id: str, user: str, *, token: ..., repo_type: ..., rejection_reason: ...) -> None

Reject access request to a gated repo.

grant_access(repo_id: str, user: str, *, token: ..., repo_type: ...) -> None

Grant access to a gated repo without an access request.

USER COLLECTIONS (8 methods)

get_collection(collection_slug: str, *, token: ...) -> Collection

Get a collection's details from the Hub.

create_collection(title: str, *, namespace: ..., description: ..., private: ..., token: ...) -> Collection

Create a new collection on the Hub.

list_collections(*, owner: ..., item: ..., sort: ..., limit: ..., token: ...) -> Iterable[Collection]

List collections on the Huggingface Hub, given some filters.

delete_collection(collection_slug: str, *, missing_ok: bool = False, token: ...) -> None

Delete a collection on the Hub.

add_collection_item(collection_slug: str, item_id: str, item_type: CollectionItemType_T, *, note: ..., exists_ok: bool = False, token: ...) -> Collection

Add an item to a collection on the Hub.

delete_collection_item(collection_slug: str, item_object_id: str, *, missing_ok: bool = False, token: ...) -> None

Delete an item from a collection.

update_collection_item(collection_slug: str, item_object_id: str, *, note: ..., position: ..., token: ...) -> None

Update an item in a collection.

update_collection_metadata(collection_slug: str, *, title: ..., description: ..., position: ..., private: ..., theme: ..., token: ...) -> Collection

Update the metadata of a collection on the Hub.

USER INTERACTIONS (3 methods)

like(repo_id: str, *, token: ..., repo_type: ...) -> None

Like a given repo on the Hub (star).

unlike(repo_id: str, *, token: ..., repo_type: ...) -> None

Unlike a given repo on the Hub (unstar).

auth_check(repo_id: str, *, repo_type: ..., token: ...) -> None

Check if the provided user token has access to a specific repository on the Hugging Face Hub.