meta-catalog: inspect metadata fields
Inspect meta-search fields, filter and sort support, and default returned columns.
Overview
meta-catalog shows which fields meta-search supports, which fields can be filtered or sorted, which columns return by default, and the available operators and sample enum values. Use it before building filters, generating query forms, or letting an agent compose meta-search requests.
Not for
- · Do not use it to search papers, retrieve evidence chunks, or read full text.
- · Do not use it to check whether a specific paper exists; use meta-search.
- · Do not use it to download resource files; use resource.
Capability boundaries
- · meta-catalog is a runtime schema-discovery endpoint returning fields, operators, and projection capabilities.
- · include_sample_values may return cached samples; samples are not exhaustive enumerations.
- · Clients should use the catalog to build meta-search requests instead of permanently hard-coding field names.
Authentication
Use API key Bearer token authentication for all requests. Add this HTTP header:
Authorization: Bearer YOUR_API_TOKEN
Request example
curl -G https://api.sciverse.space/meta-catalog \
-H "Authorization: Bearer YOUR_API_TOKEN" \
--data-urlencode "include_sample_values=true"Request parameters (URL query)
| Field | Type | Required | Description |
|---|---|---|---|
| collection | string | Optional | Entity collection the field catalog belongs to. papers (default) / authors / sources; each collection has a different field schema. Default papersRange papers / authors / sources |
| include_sample_values | bool | Optional | Whether to return sample values for enum-like fields. Sample values are cached for 24 hours. Default false |
Response structure
| Field | Type | Description |
|---|---|---|
| fields | array | Field list. |
| fields[].name | string | Field name. |
| fields[].type | string | Type: String / Integer / Float / List[...]. |
| fields[].filterable | bool | Whether the field can be used in filters. |
| fields[].sortable | bool | Whether the field is sortable. |
| fields[].searchable | bool | Whether the field is searchable. |
| fields[].default_returned | bool | Whether the field is returned by default. |
| fields[].description | string | Field description. |
| fields[].sample_values | array | Sample enum values, returned only when include_sample_values=true. |
| fields[].operators | array | Operators supported by the field; Integer/Float fields usually support all operators, List fields often support IN/NIN/CONTAINS, and non-filterable fields return an empty array. |
| default_fields | array | Default returned field set. |
| filter_operators | array | Globally supported filter operators: EQ / NE / GT / GTE / LT / LTE / IN / NIN / CONTAINS / MATCH / MATCH_PHRASE. MATCH is tokenized fuzzy match (author, keywords); MATCH_PHRASE is phrase fuzzy match (publication_venue_name_unified). |
Errors
| Code | Message | Description |
|---|---|---|
| 401 | UNAUTHORIZED | Authentication failed. |
| 429 | RATE_LIMITED | Account quota limit reached. |
| 502 | UPSTREAM_UNAVAILABLE | Service error. |
| 503 | METADATA_GRPC_NOT_CONFIGURED / UPSTREAM_ERROR | The metadata service is temporarily unavailable. Please retry later. |
See the Errors section for shared error codes.
Parameter bounds
| Limit | Value |
|---|---|
| Sample values default | Not fetched by default; set include_sample_values=true. |
| doc_id | Always visible |
Retry guidance
- · Retry recommended: 502 / 503 / 504
- · Do not retry: 401
FAQ
When should I call meta-catalog?
Call it before an agent or UI builds meta-search filters, field pickers, or sort controls.
Are sample values complete enums?
No. They are samples or cached examples for UI and prompting, not the full value space.
Does meta-catalog return paper results?
No. It returns schema and field capabilities. Paper results come from meta-search.
Can field permissions change the catalog?
Yes. Different accounts or roles may see different field capabilities, so callers should build requests from the returned catalog.
Need an API key?
Create one in Console > Tokens.The same API key works for enabled Sciverse, DianShi, and Skills capabilities, with starter quota available according to account permissions.