Artifacts
Agent Docs

Stable v1 artifact search alias.

Agent-friendly alias for /api/artifacts with summary=1 by default, including searches without q. Use summary=0 or detail=full for rich rows. Use this for bounded catalog retrieval from ChatGPT, Perplexity, Claude, Gemini, OpenClaw, Hermes, and local agents.

Inputs. Path, query and header fields are listed below. No request body is required.

Outputs. See each status below for its media type, schema and headers. A missing record or unavailable capability is not a successful empty result.

Errors. API JSON failures use the documented response schema. Read code, message and next; retry only when the response allows it. Auth, invalid input and missing records need a caller change.

Rate limits. Public read budgets apply by client IP and route group. This operation can have a smaller route-specific budget. Read Retry-After on 429 or retryable 503 responses.

get/api/v1/search

Request

  • Base URL: https://huggingbay.xyz
  • URL: https://huggingbay.xyz/api/v1/search
  • Auth: none declared

Query parameters

summary'0' | '1'

Compact summary rows; summary=0 opts into rich rows.

detail'summary' | 'full'

Use detail=full for rich rows when summary is absent. An explicit summary choice takes precedence.

qstring
typestring
licensestring
taskstring

Pipeline task or Browse alias: code requires text-generation plus a coding name/tag; chat requires conversational or text-generation plus an instruct/chat name/tag; pictures means text-to-image.

size'small' | 'medium' | 'large'

Recorded default weight download: small <= 2 GB, medium > 2 and <= 8 GB, large > 8 GB (decimal GB). Unknown or incomplete sizes are excluded and counted in unknownSizeExcluded.

formatstring
sourcestring
hostingstring
uncensored'only' | 'exclude'

Plain filter (default: shown like everything else). only = abliterated/uncensored/unfiltered models (repo name or plain tag); exclude = leave them out.

nsfw'only' | 'exclude'

Plain filter (default: shown like everything else). only = models tagged not-for-all-audiences or nsfw (tags, card metadata, or an nsfw token in the repo id); exclude = leave them out.

scanState'flagged' | 'clean'

Scan-flag LABEL filter (never a download gate). flagged = at least one served file whose independent scan reported findings; it stays downloadable and is labelled "Security scan flagged this file". Rows carry scanState "flagged", scanLabel and scanFlaggedFiles; file rows (download-plan, files) carry scanState / scanLabel / scanFindings.

licenseState'none' | 'unknown' | 'known' | 'no-license'

Licence LABEL filter (never a download gate; every state stays downloadable). none = no licence metadata; unknown = a stated but unresolved licence such as unknown / unnamed other (both labeled "License: unknown"); known = a licence we can name; no-license = the "No license" category (none + unknown). Rows carry licenseState / licenseLabel / licenseCategory; facets.licenseState counts none / unknown / known plus the no-license category row.

reviewStatus'first-review' | 'needs-evidence' | 'reviewed' | 'benchmark'

Filter by review and run-report evidence state.

commercialstring
semantic'1'

Use semantic=1 for hybrid semantic reranking of natural-language artifact queries.

explain'1'

Include token expansion and semantic score diagnostics.

sort'best' | 'ready' | 'mirrorable' | 'trust' | 'rating' | 'updated' | 'downloads' | 'stars' | 'mirrors' | 'demand' | 'name' | 'size' | 'license'
limitinteger
cursorinteger

Start with cursor=0 and follow nextCursor. offset and page are unsupported.

compat'containment'

Deprecated legacy response block opt-in for one release only.

Response

Artifact page

rowsArtifactSummary[] required(unresolved $ref)
unknownSizeExcludedinteger

Matching records excluded by the size filter because the default download has no complete recorded byte size. Counted before pagination with the other query filters applied.

totalnumber required
limitnumber required
cursorstring required
nextCursorstring nullable required
facetsFacetCounts (unresolved $ref)
facetsApproximateboolean

True when facet counts cover a bounded search candidate set or returned page rather than the complete matching catalog.

facetsScope'bounded-search-candidates' | 'returned-search-page' | 'degraded-fallback-results' | 'no-match'
facetsPartialboolean

True when facets cover only the returned page because complete matching-catalog facet counts were unavailable within the bounded search deadline.

facetsUnavailableboolean

True when no facet counts could be derived because the bounded result page was empty and no complete cached facet result was available.

facetsGeneratedAtstring date-time

Timestamp for the returned complete or page-scoped facet result.

estimatedTotalboolean

True when total is bounded or estimated and must not be treated as the complete matching catalog count. Within one query the total is stable across every cursor page.

degradedboolean

True only when the response came from a degraded, stale, or fallback catalog read after a backend error. A well-formed query with no matches is degraded:false, partial:false, total:0 with reason:"no_match".

partialboolean

True when returned rows may omit matching catalog entries because of a backend error; zero rows or totals are then not authoritative. Never set on a clean no-match page.

reason'no_match' | 'cursor_past_end'

Why a healthy response carries zero rows: no_match (nothing matched; total is 0) or cursor_past_end (the cursor is beyond the stable total; nextCursor is null).

retryableboolean

True when retrying may recover a more complete catalog response.

retryAfterSecondsinteger

Suggested minimum delay before retrying a degraded catalog response.

warningstring
fastPathstring
generatedAtstring required

Changes

No recorded changes to this operation across all 1 revision of this API.