# Zmass AI Asset Usage: Search-First Agent Access

Base URL: `https://zmass.ai`

## 1. Overview

Zmass assets are served through a controlled asset broker. AI agents do not get repo access, folder access, raw Blob listing access, or all-assets download access.

Agents can:

- Search asset metadata for a specific scene need.
- Inspect metadata and preview-only information for a selected asset.
- Request one production file at a time after scope, quota, project, and credit checks.
- Stream the approved file through a short-lived broker token.

Production files are not exposed through public Vercel Blob URLs.

## 2. API Key Safety

Send the key as a bearer token:

```bash
curl -H "Authorization: Bearer zma_your_key_here" \
  "https://zmass.ai/api/assets/search?q=jungle%20tree&type=model&limit=10"
```

`X-API-Key: zma_your_key_here` also works.

Never place a Zmass API key in public repos, browser client code, public prompts, issue trackers, logs, or screenshots.

## 3. Scopes

Common scopes:

- `assets:search`
- `assets:detail`
- `assets:preview`
- `assets:download`
- `assets:model:download`
- `assets:texture:download`
- `assets:bulk-download`
- `admin:assets`

New keys default to search, detail, and preview only. Production download scopes must be explicitly enabled from the dashboard.

## 4. Search Assets

Use search first. `q` is required unless `featured=true`.

```bash
curl -H "Authorization: Bearer zma_your_key_here" \
  "https://zmass.ai/api/assets/search?q=jungle%20tree&type=model&limit=10"
```

Optional filters:

- `type=model|texture|material|animation|scene`
- `biome=tropical|forest|desert|meadow|built|terrain|general`
- `tags=tree,tropical`
- `limit=10`, capped at 20

Search results return metadata and preview route URLs only. They never return production file URLs or private Blob pathnames.

## 5. Inspect Asset Metadata

```bash
curl -H "Authorization: Bearer zma_your_key_here" \
  "https://zmass.ai/api/assets/model-palm-tree"
```

The detail response includes asset description, tags, biome, preview URLs, available file roles, file sizes, credit costs, license tier, and required scopes.

It does not include production Blob URLs or private Blob pathnames.

## 6. Request Production Download

Request exactly one production file role for the current project:

```bash
curl -X POST \
  -H "Authorization: Bearer zma_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "vibe-game-001",
    "fileRole": "model",
    "reason": "Selected palm tree for the playable jungle beach scene"
  }' \
  "https://zmass.ai/api/assets/model-palm-tree/download-request"
```

Required fields:

- `projectId`
- `fileRole`
- `reason`

The key must be active, have `assets:download`, have the asset type scope such as `assets:model:download`, and have enough quota/credits.

## 7. Stream With Short-Lived Token

A successful request returns:

```json
{
  "downloadToken": "zmdl_...",
  "expiresInSeconds": 300,
  "assetId": "model-palm-tree",
  "fileRole": "model",
  "creditCost": 2,
  "creditsDeducted": "on_successful_stream_start",
  "downloadUrl": "/api/downloads/zmdl_..."
}
```

Then stream through the broker:

```bash
curl -L \
  "https://zmass.ai/api/downloads/zmdl_download_token_here" \
  -o palm-tree.glb
```

The token is short-lived and single-use. The broker streams the private Blob file; it does not redirect to a public production Blob URL.

## 8. Quotas And Credits

Keys can have daily search limits, daily preview limits, daily download limits, monthly download limits, monthly credit limits, max search result limits, and request-rate limits.

Credits are counted when the production stream begins successfully.

## 9. Agent Rules

- Do not call the API to list every asset.
- Do not crawl asset IDs.
- Do not search by only `type=model` or `type=texture`.
- Do not request production files until the scene has selected the asset.
- Request one production file role at a time.
- Always include `projectId`, `fileRole`, and `reason`.
- Use previews and metadata to decide before requesting downloads.

## 10. Error Codes

Common errors:

- `missing_api_key`
- `api_key_disabled`
- `missing_scope`
- `search_query_required`
- `search_rate_limited`
- `daily_search_limit`
- `download_rate_limited`
- `daily_download_limit`
- `monthly_download_limit`
- `monthly_credit_limit`
- `project_id_required`
- `reason_required`
- `file_role_required`
- `asset_not_found`
- `file_role_not_found`
- `download_token_expired`
- `download_token_used`

Use the error message to narrow the request. Do not retry a denied broad enumeration request.

## 11. Example: Jungle Environment Asset Selection

1. Search:

```bash
curl -H "Authorization: Bearer zma_your_key_here" \
  "https://zmass.ai/api/assets/search?q=jungle%20palm%20tree&type=model&limit=10"
```

2. Inspect:

```bash
curl -H "Authorization: Bearer zma_your_key_here" \
  "https://zmass.ai/api/assets/model-palm-tree"
```

3. Request the selected model:

```bash
curl -X POST \
  -H "Authorization: Bearer zma_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"projectId":"jungle-runner","fileRole":"model","reason":"Use this palm as the main beach jungle tree prop"}' \
  "https://zmass.ai/api/assets/model-palm-tree/download-request"
```

4. Stream with the returned token:

```bash
curl "https://zmass.ai/api/downloads/zmdl_download_token_here" -o model-palm-tree.glb
```

## 12. Anti-Crawling Policy

The broker logs every search, detail view, preview, download request, successful download stream, denial, and rate-limit event.

The broker blocks or flags:

- Empty searches.
- Broad type-only enumeration.
- Excessive search/detail/download rates.
- Too many unique assets requested in a short window.
- Reused or expired download tokens.
- Attempts to use legacy endpoints for signed production URLs.

Production files remain private in Vercel Blob and are only served through broker-checked routes.