Skip to content
Hayonix

API reference · Model references

Accept a model reference (checked against the model hub, pinned to a commit)

POST/v1/model-references
API keymodel_reference:createProjectIdempotency-Key
TypeScript
client.modelReferences.create()
Python
client.model_references.create()
CLI
hayonix model-references create

Checks a model on the model hub and records it for this project: the revision is pinned to its commit, and the files (all, or those matching include) are listed with their sizes and digests. Nothing is downloaded now; hosts download and verify the files when a workload that mounts the reference starts. A private or gated model needs token_secret_id; its files are then cached for this project only.

Project API key (Authorization: Bearer sk_…), or a console session. Requires the model_reference:create 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" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "hf-internal-testing/tiny-random-gpt2@main",
  "include": [
    "*.json",
    "*.safetensors"
  ]
}'

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.
Idempotency-KeynoMakes a retry safe: the same key and request within 24 hours return the original response (see Idempotency). The SDKs send one for you.

Body

JSON (application/json): CreateModelReferenceRequest.

  • modelstringrequired

    The model on the model hub, as <owner>/<name> or <owner>/<name>@<revision>. The revision (a branch, tag or commit; default main) is pinned to its commit now, so a moving branch never changes what runs.

    3–300 characters

  • includearray of string

    Only files matching one of these patterns (`*` matches any characters including "/", `?` one character). Default: every file of the revision.

    up to 32 items

  • token_secret_idstring | null

    A project secret holding a model hub access token, for private or gated repositories. Hosts download with it and keep the files for this project only; containers never see it.

    ID with prefix sec_

Response

201 ModelReference — What the reference resolved to

  • 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)

Example response
Example response
{
  "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"
}

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.
409conflict_error idempotency_in_progressA request with the same Idempotency-Key is still running.
422idempotency_error idempotency_key_reusedThe Idempotency-Key was used with a different request.
429rate_limit_error rate_limitedToo many requests; retry after retry-after seconds.