Artifacts
Agent Docs

Hybrid semantic artifact search.

Self-describing alias for /api/artifacts?summary=1&semantic=1&explain=1. Use this for natural-language questions from answer engines, OpenClaw, Hermes, coding agents, and local assistants.

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/search/semantic

Request

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

Query parameters

qstring required

Natural-language artifact search, for example best small commercial embedding model for RAG.

typestring
licensestring
formatstring
worksWithstring
hostingstring
reviewStatus'first-review' | 'needs-evidence' | 'reviewed' | 'benchmark'
commercialstring
limitinteger
cursorstring

Response

Semantically reranked 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.