Artifacts

Search and page through public artifacts.

Alias of /api/v1/search (recorded; identical handler). Prefer the recorded path: this one already answers with Deprecation and Sunset headers.

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/artifacts

Request

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

Query parameters

summary'1'

Use summary=1 for bounded agent-friendly rows.

qstring

Lexical query with Hugging Bay intent expansion for terms like rag, local, coding, image, agent, and safe.

explain'1'

Use explain=1 with q to include expanded token groups and per-row searchExplanation match fields.

semantic'1'

Use semantic=1 with q for hybrid semantic reranking. Also available as /api/search/semantic?q=...

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
worksWith'ollama' | 'lm-studio' | 'comfyui' | 'transformers' | 'llama.cpp'

Filter by local/runtime integration hints.

ownerstring

Filter to one publisher namespace or artifact owner.

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

Filter by community trust evidence state.

facets'1'

Include facet counts. Broad unfiltered queries use catalog-wide counts; q and licence-only searches may return bounded counts identified by facetsApproximate, facetsScope, facetsPartial, and facetsGeneratedAt.

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

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.