manifest:
  id: free3d-public-api-manifest
  updated_at: 2026-03-13
  mode: strict
  fallbacks: forbidden
  owner: free3d.online
  purpose:
    - machine-readable current contract for main-site, plugins, and worker integration
    - stable source of truth for live routes and direct-file download behavior
    - public reference for developers, automation, and AI agents

sources_of_truth:
  public_manifest_url: https://free3d.online/api/manifest.yaml
  public_manifest_alias_url: https://free3d.online/api/manifest
  api_docs_url: https://free3d.online/api-docs
  worker_manifest_url: https://free3d.online/assets/manifests/worker-manifest.yaml
  worker_guide_url: https://free3d.online/assets/manifests/worker-guide.md
  plugin_manifest_url: https://free3d.online/assets/manifests/plugin-manifest.yaml
  plugin_guide_url: https://free3d.online/assets/manifests/plugin-guide.md

global_rules:
  https_only_browser_urls: true
  direct_pipeline_only: true
  fallback_behavior: forbidden
  canonical_model_route: /model/{guid}-{slug}
  prepare_stage: forbidden

runtime:
  main_site_public_base_url: https://free3d.online
  worker_public_base_url: https://worker-0001.free3d.online
  preferred_download_mode: direct_file_inventory
  public_auth_flows:
    - user_token
    - plugin_token
  public_download_flows:
    - browser
    - api
    - plugin

auth:
  session_auth_used_on_main_site: true
  user_token_headers:
    - Authorization: Bearer <api_token>
    - X-API-Key: <api_token>
  plugin_token_headers:
    - Authorization: Bearer <plugin_token>
    - X-Plugin-Token: <plugin_token>
  worker_server_to_server_auth_headers:
    - X-Worker-Token
    - Authorization: Bearer <token>

main_site:
  public_routes:
    - path: /
      type: html
      auth: public
    - path: /api-docs
      type: html
      auth: public
    - path: /search
      type: html
      auth: public
    - path: /guides
      type: html
      auth: public
    - path: /plugins
      type: html
      auth: public
    - path: /model/{guid}-{slug}
      type: html
      auth: public
      canonical: true
    - path: /robots.txt
      type: text
      auth: public
    - path: /sitemap.xml
      type: xml
      auth: public
    - path: /assets/{path}
      type: static
      auth: public

  public_api_routes:
    - path: /health
      method: GET
      auth: public
    - path: /api/category-mapping.json
      method: GET
      auth: public
    - path: /api-embeddings/browse
      method: GET
      auth: public
    - path: /api-embeddings/
      method: GET
      auth: public
    - path: /api-embeddings/filters
      method: GET
      auth: public
    - path: /api-home/stats
      method: GET
      auth: public
    - path: /viewer-asset/{guid}/{asset_kind}
      method: GET
      auth: public
    - path: /api-model-view/{guid}/{asset_kind}
      method: GET
      auth: public

  user_token_routes:
    - path: /api/auth/token
      method: GET
      auth: session_required
    - path: /api/auth/register
      method: POST
      auth: public
    - path: /api/auth/login
      method: POST
      auth: public
    - path: /api/account
      method: GET
      auth: api_token_required
    - path: /api/account/balance
      method: GET
      auth: api_token_required
    - path: /api/download/formats/{guid}
      method: GET
      auth: api_token_required
      purpose: list exact direct-file descriptors for authenticated API clients
    - path: /api/download/direct
      method: POST
      auth: api_token_required
      purpose: authorize, charge if needed, record, and return final worker directUrl

  plugin_auth_routes:
    - path: /api/apps/auth/start
      method: POST
      auth: public
    - path: /api/apps/auth/authorize/{session_id}
      method: GET
      auth: session_required
    - path: /api/apps/auth/confirm
      method: POST
      auth: session_required
    - path: /api/apps/auth/poll/{session_id}
      method: GET
      auth: poll_token_required
    - path: /api/apps/auth/revoke
      method: POST
      auth: plugin_token_required

  plugin_routes:
    - path: /api/plugin/account
      method: GET
      auth: plugin_token_required
    - path: /api/plugin/account/balance
      method: GET
      auth: plugin_token_required
    - path: /api/plugin/account/entitlements
      method: GET
      auth: plugin_token_required
    - path: /api/plugin/download/formats/{guid}
      method: GET
      auth: plugin_token_required
      purpose: list direct-file scene variants and import metadata for plugins
    - path: /api/plugin/download/direct
      method: POST
      auth: plugin_token_required
      purpose: authorize, charge if needed, record, and return final worker directUrl plus support files

  browser_download_routes:
    - path: /download/{guid}/format/{ext}
      method: GET
      auth: required
      required_query:
        - lod
        - relativePath
    - path: /download/{guid}/textures
      method: GET
      auth: required
      required_query:
        - ext
        - lod
        - relativePath
    - path: /download/{guid}/all
      method: GET
      auth: required
      required_query:
        - ext
        - lod
        - relativePath

  model_detail_requirements:
    default_download_label: Download .fbx {selected_topology}
    preferred_format_order:
      - fbx
      - glb
      - max
      - blend
      - obj
    topology_values:
      - 1k
      - 10k
      - 100k
    format_ui_mode: topology_selector_plus_format_selector_plus_actions
    format_ui_source: meta_summary.downloadUi
    preferred_format_persisted_in_session_storage: true
    hide_source_topology_when_per_lod_variants_exist: true

  generated_archive_policy:
    enabled: true
    compression: store_only
    ttl_seconds: 3600
    cleanup_interval_seconds: 300
    archive_types:
      - textures
      - all

pricing_rules:
  first_unlock_per_model_usd: 1
  repeated_download_after_unlock_usd: 0
  unlimited_subscription_usd: 0

worker_sync:
  strict_mode: true
  prepare_stage: forbidden
  required_routes:
    - path: /api-sync/status
      method: GET
      auth: public
    - path: /api-sync/status.json
      method: GET
      auth: public
    - path: /api-sync/changes
      method: GET
      auth: required
    - path: /api-sync/product/{guid}
      method: GET
      auth: required
  forbidden_routes:
    - path: /api-download/prepare
      reason: direct static files are the only supported public download contract
  status_contract:
    required_fields:
      - ok
      - version
      - latestWorkerVersion
      - staticFilesEnabled
      - productsCount
      - posterCoverage
      - previewCoverage
  product_contract:
    required_fields:
      - guid
      - version
      - type
      - title
      - description
      - keywords
      - updatedAt
      - deleted
      - hash
      - assets
      - files
    file_inventory_rules:
      direct_url_required: true
      direct_url_https_only: true
      browser_default_hint_supported: true
      support_files_relative_paths_required: true

machine_consumption:
  preferred_fetch_url: https://free3d.online/api/manifest.yaml
  format: yaml
  update_strategy: poll_latest_before_integrating
  unknown_fields_policy: ignore_but_do_not_guess
  missing_required_fields_policy: fail_and_report

status:
  manifest_endpoint: live
  worker_manifest_public: true
  worker_guide_public: true
  plugin_manifest_public: true
  plugin_guide_public: true
  prepare_references_in_live_contracts: false
