Hub API#

The canonical Hub API is the language-neutral interface for repositories, accounts, organizations, community workflows, compute, billing, and platform integrations. Its routes are rooted directly at /api; use the live OpenAPI document for exact schemas and this guide for the shared conventions.

Base URLs#

Inference uses a separate public Router hostname and error shape. See Inference Providers and the Router API Reference before sending model traffic there.

Authenticate#

Send a fine-grained token as a bearer credential:

1curl https://mega.tensorplay.cn/api/whoami \2  -H "Authorization: Bearer $MEGA_TOKEN"

Public repository and catalog reads can be anonymous. Private reads and mutations require authentication plus the necessary token scope and owner or organization permission.

Browser-session endpoints under /api/me, checkout, organization settings, and other interactive security flows may deliberately reject bearer-token automation. Use the CLI or typed client for supported automation instead of copying browser cookies.

Send JSON correctly#

JSON mutations require Content-Type: application/json:

1curl -X POST https://mega.tensorplay.cn/api/repos \2  -H "Authorization: Bearer $MEGA_TOKEN" \3  -H "Content-Type: application/json" \4  --data '{5    "repo_id": "alice/api-demo",6    "repo_type": "model",7    "private": true,8    "description": "Repository created through the Hub API",9    "tags": ["demo"]10  }'

The response status is 201 for a new repository. Use the returned repository and revision fields rather than reconstructing server identifiers.

Repository paths and types#

All four repository types use the same API collection:

/api/repos/{owner}/{name}

The repo_type field distinguishes model, dataset, space, and mcp. Browser presentation adds /datasets/, /spaces/, or /mcps/ prefixes, but those prefixes are not part of the canonical /api/repos identity.

Repository file reads resolve a branch, tag, or commit through:

GET /api/repos/{owner}/{name}/resolve/{path}?revision=v1.0

Resolver responses include content length, ETag, SHA-256, and resolved-commit metadata. Byte ranges are supported for large artifacts; a valid range returns 206 with Content-Range.

Paginate collections#

Collection responses use an opaque continuation field, usually next_cursor:

1{2  "repos": [],3  "next_cursor": "opaque-value-or-null"4}

Pass the value back as cursor with the same filters and sort order. Do not decode, edit, compare, or persist assumptions about cursor contents. A null cursor means the collection is complete.

Limits differ by resource. Repository search accepts up to 500 items, while Papers and other collections use smaller caps. Follow the OpenAPI constraint for the specific operation.

Handle errors#

Most Hub failures return a JSON object with a human-readable error string and the matching HTTP status:

{ "error": "repository not found" }

Common statuses are:

OAuth, SCIM, Git LFS, and OpenAI-compatible inference follow their protocol-specific error contracts. Use the relevant OpenAPI response instead of assuming the generic Hub shape.

Endpoint groups#

Choose a client#

• Use the MEGA CLI for shell workflows, resumable transfers, and CI-friendly exit codes.
• Use MegaHubClient for typed Python repository, Job, and webhook methods.
• Use the raw API for other languages or when the typed client does not expose a newly deployed operation yet.
• Use MCP when an AI client needs a deliberately selected tool surface rather than unrestricted HTTP access.

Generate clients only from the live OpenAPI document and preserve unknown response fields so additive server changes do not break consumers.