Skip to content
Hayonix

API reference · Model references

List the project’s model references

GET/v1/model-references
API keymodel_reference:readProjectPaginated
TypeScript
client.modelReferences.list()
Python
client.model_references.list()
CLI
hayonix model-references list

The project’s model references, newest first.

Project API key (Authorization: Bearer sk_…), or a console session. Requires the model_reference:read permission (a key's scope, or a role that includes it).

Examples

The samples read API_KEY and API_BASE_URL from the environment (see Setup). Values are examples.

curl -sS "$API_BASE_URL/model-references" \
  -H "Authorization: Bearer $API_KEY"

Request

Headers
HeaderRequiredDescription
AuthorizationyesBearer and your API key. The key implies its project.
X-Project-Idsession onlyThe project to act in, for console sessions. Requests with an API key leave it out.

Query parameters

  • limitinteger

    1–200, default 50

    1–200

  • cursorstring

    `next_cursor` of the previous page

    up to 200 characters

Response

200 a page of results — A page of references, newest first

  • The items of this page.

    Show 14 fields of data
    • objectstringrequired

      Always `model_reference`: the type of this object

      One ofmodel_reference

    • idstringrequired

      Unique ID (`mrf_…`)

      ID with prefix mrf_

    • repositorystringrequired

      The repository on the model hub, as <owner>/<name>

    • requested_revisionstringrequired

      The branch, tag or commit the reference named when it was accepted

    • commitstringrequired

      The 40-character commit the revision resolved to

    • includearray of stringrequired

      The file patterns it was limited to (empty: every file)

    • visibilitystringrequired

      private: fetched with token_secret_id and cached on hosts for this project only

      One ofpublicprivate

    • token_secret_idstring | nullrequired

      ID of the token secret

    • file_countintegerrequired

      How many files it holds

    • total_bytesintegerrequired

      The size of all its files together, in bytes

    • Every file, with the size and digest each is verified against on the host

      Show 4 fields of files
      • pathstringrequired

        Path of the file inside the repository

      • sizeintegerrequired

        Size of the file in bytes

      • sha256string | nullrequired

        Large files: SHA-256 of the content

      • git_blob_sha1string | nullrequired

        Small files: the version-control object ID

    • mount_pathstringrequired

      Where it appears in a container: the cache layout the model hub client libraries read, so they find it with networking off

    • snapshot_pathstringrequired

      The directory holding its files inside a container

    • created_atstring (date-time)required

      When it was created (ISO 8601, UTC)

  • next_cursorstring | nullrequired

    Pass as `cursor` for the next page; null on the last page.

Example response
Example response
{
  "data": [
    {
      "object": "model_reference",
      "id": "mrf_01jc5zq4m8k3v6x9t2w7r0b1e4",
      "repository": "hf-internal-testing/tiny-random-gpt2",
      "requested_revision": "string",
      "commit": "string",
      "include": [
        "string"
      ],
      "visibility": "public",
      "token_secret_id": "string",
      "file_count": 1,
      "total_bytes": 1,
      "files": [
        {
          "path": "string",
          "size": 1,
          "sha256": "string",
          "git_blob_sha1": "string"
        }
      ],
      "mount_path": "/model-cache/models--hf-internal-testing--tiny-random-gpt2",
      "snapshot_path": "string",
      "created_at": "2026-01-01T00:00:00.000Z"
    }
  ],
  "next_cursor": "string"
}

Errors

Errors use the standard envelope. What this operation can answer:

Errors
StatusTypeWhen
400invalid_request_errorA parameter or body field is missing or not allowed; param names it.
401authentication_errorThe key or session is missing, revoked or expired.
403permission_errorThe credential lacks the permission this needs, or the organization is suspended.
429rate_limit_error rate_limitedToo many requests; retry after retry-after seconds.