// Model Management

Model Sharing

Publish a model into the public catalog without surrendering the weights. Sharing exposes the manifest only; storage stays yours, visibility is revocable, and other operators run it on their own hardware or on a shared tier.

When you share a model:

  • The model becomes visible in the public catalog.
  • Other Xerotier.ai users can discover the model and create endpoints against it.
  • You retain ownership and can unshare at any time.
  • Already-provisioned endpoints keep serving traffic after you unshare. The catalog footprint (deployment count, featured flag, catalog role) is removed; new endpoints on shared tiers can no longer select the model.

Catalog Roles

Every model in the public catalog carries a catalog role that decides which service tiers may select it.

Role Description Allowed Tiers
deployable Default role assigned at share time. Visible in the catalog; selectable only from the self-hosted tier. self_hosted only
shared Also available to endpoints on non-self-hosted (shared) tiers. All tiers. Tier slugs: Service Tiers.

A freshly shared model always starts at deployable. Demotion back to deployable is automatic: when the count of active non-self_hosted endpoints for the model drops to zero, the role resets.

Planned: automatic promotion from deployable to shared when an endpoint is created on a non-self_hosted tier is on the roadmap. Today no code path assigns shared, so a freshly shared model remains deployable until that promotion mechanism ships.

Shared Model Volatility

If your workload requires guaranteed availability, use self_hosted. Self-hosted nodes are under your control and the platform will not evict their models. See Service Tiers for tier slugs and details.

Share Model

POST /proj_ABC123/v1/models/{modelId}/share

Shares a model to the public catalog, making it discoverable and usable by other Xerotier.ai users.

Requirements

  • A valid project-scoped API key for the project that owns the model.
  • Model status is ready or active. Models in pending, processing, failed, or deleted are rejected with HTTP 400.
curl
curl -X POST https://api.xerotier.ai/proj_ABC123/v1/models/9c1f7a52-3b6d-4f2a-8e10-a3d4f0e21b77/share \ -H "Authorization: Bearer xero_myproject_your_api_key"
Python
import requests API_KEY = "xero_myproject_your_api_key" BASE_URL = "https://api.xerotier.ai/proj_ABC123/v1" MODEL_ID = "9c1f7a52-3b6d-4f2a-8e10-a3d4f0e21b77" response = requests.post( f"{BASE_URL}/models/{MODEL_ID}/share", headers={"Authorization": f"Bearer {API_KEY}"} ) if response.status_code == 200: data = response.json() print(f"Model shared: {data['shared']}") else: print(f"Error: {response.json()}")
Node.js
const MODEL_ID = "9c1f7a52-3b6d-4f2a-8e10-a3d4f0e21b77"; const response = await fetch( `https://api.xerotier.ai/proj_ABC123/v1/models/${MODEL_ID}/share`, { method: "POST", headers: { "Authorization": "Bearer xero_myproject_your_api_key" } } ); if (response.ok) { const data = await response.json(); console.log(`Model shared: ${data.shared}`); } else { const error = await response.json(); console.log(`Error: ${JSON.stringify(error)}`); }

Response

{ "id": "9c1f7a52-3b6d-4f2a-8e10-a3d4f0e21b77", "shared": true, "message": "Model shared to catalog", "catalog_role": "deployable" }

catalog_role: "deployable" means the model is in the catalog but is not yet selectable from shared tiers. See Catalog Roles for the promotion rule.

Unshare Model

POST /proj_ABC123/v1/models/{modelId}/unshare

Removes the model from the public catalog. The model is no longer discoverable; endpoints already using it continue to function.

Requirements

  • A valid project-scoped API key for the project that owns the model.
  • If the model is not currently shared, the call is a no-op and still returns HTTP 200 with shared: false.
curl
curl -X POST https://api.xerotier.ai/proj_ABC123/v1/models/9c1f7a52-3b6d-4f2a-8e10-a3d4f0e21b77/unshare \ -H "Authorization: Bearer xero_myproject_your_api_key"
Python
import requests API_KEY = "xero_myproject_your_api_key" BASE_URL = "https://api.xerotier.ai/proj_ABC123/v1" MODEL_ID = "9c1f7a52-3b6d-4f2a-8e10-a3d4f0e21b77" response = requests.post( f"{BASE_URL}/models/{MODEL_ID}/unshare", headers={"Authorization": f"Bearer {API_KEY}"} ) if response.status_code == 200: data = response.json() print(f"Model unshared: {not data['shared']}") else: print(f"Error: {response.json()}")
Node.js
const MODEL_ID = "9c1f7a52-3b6d-4f2a-8e10-a3d4f0e21b77"; const response = await fetch( `https://api.xerotier.ai/proj_ABC123/v1/models/${MODEL_ID}/unshare`, { method: "POST", headers: { "Authorization": "Bearer xero_myproject_your_api_key" } } ); if (response.ok) { const data = await response.json(); console.log(`Model unshared: ${!data.shared}`); } else { const error = await response.json(); console.log(`Error: ${JSON.stringify(error)}`); }

Response

{ "id": "9c1f7a52-3b6d-4f2a-8e10-a3d4f0e21b77", "shared": false, "message": "Model removed from catalog", "catalog_role": null }

Error Responses

Share and unshare return the standard error envelope with a plain message field. The handlers do not emit structured error slugs; the table lists the HTTP status, the literal message the router emits today, and the remediation path.

HTTP Status Message Cause & Remediation
401 Authentication required No valid API key was presented, or the key did not resolve to a project. Mint a project-scoped key in the dashboard and resend.
400 Invalid model ID The path parameter is not a UUID. Confirm the id from GET /v1/models.
400 (sanitized database error; varies) Returned by share when the model does not exist, is owned by another project, or is not in ready/active status. Confirm ownership and status via GET /v1/models/{id} and retry once status transitions to ready or active.
404 Model not found or not shared Returned by unshare when the model does not exist or is not owned by the calling project. Confirm ownership via GET /v1/models.

See Also

  • Model Upload Prerequisite. The model must exist and reach ready before it can be shared.
  • Model Management Sibling. List, rename, and delete models. Share / unshare lives here in spirit.
  • Service Tiers Tier slugs and what each one allows.
  • Model Catalog Reader side: how shared models surface to other operators.