Catalogs API

List registered data catalogs in the Spice runtime

Overview

The Catalogs API provides an endpoint to list all registered data catalogs. Catalogs provide metadata about schemas and tables available from external data sources.

List Catalogs

GET /v1/catalogs

Returns a list of all registered catalogs in the runtime.

Query Parameters

from · string

Filter catalogs by source provider (e.g., spiceai, unity, databricks)

Request Headers

Accept · string · default: "application/json"

The desired response format:

• application/json - JSON array (default)
• text/csv - CSV format

Response

(array) · array<object>

Array of catalog information objects.

from · string

The catalog provider (e.g., spiceai, unity, databricks, postgres)

name · string

The name of the catalog as configured in the spicepod

Response Example (JSON)

[
  {
    "from": "spiceai",
    "name": "spiceai"
  },
  {
    "from": "databricks",
    "name": "my_databricks_catalog"
  },
  {
    "from": "unity",
    "name": "unity_catalog"
  }
]

Response Example (CSV)

from,name
spiceai,spiceai
databricks,my_databricks_catalog
unity,unity_catalog

Status Codes

• 200 OK - Catalogs retrieved successfully
• 500 Internal Server Error - App not initialized or unexpected error

Error Response (500)

{
  "error": "An unexpected error occurred while processing the catalogs"
}

Examples

List All Catalogs (JSON)

curl http://localhost:8090/v1/catalogs

List All Catalogs (CSV)

curl -H "Accept: text/csv" http://localhost:8090/v1/catalogs

Filter by Provider

curl http://localhost:8090/v1/catalogs?from=spiceai

curl http://localhost:8090/v1/catalogs?from=databricks

Use Cases

Discover Available Catalogs

Use this endpoint to discover what data catalogs are available in your Spice runtime:

curl http://localhost:8090/v1/catalogs | jq '.[] | .name'

Filter by Catalog Provider

When working with multiple catalog types, filter by provider to find specific catalogs:

# List only Databricks catalogs
curl http://localhost:8090/v1/catalogs?from=databricks

# List only Spice.ai catalogs
curl http://localhost:8090/v1/catalogs?from=spiceai

Integration with Data Discovery Tools

Export catalog information for data discovery and lineage tools:

# Export to CSV for analysis
curl -H "Accept: text/csv" http://localhost:8090/v1/catalogs > catalogs.csv

Programmatic Access

import requests

response = requests.get('http://localhost:8090/v1/catalogs')
catalogs = response.json()

for catalog in catalogs:
    print(f"Catalog: {catalog['name']} (Provider: {catalog['from']})")

const response = await fetch('http://localhost:8090/v1/catalogs');
const catalogs = await response.json();

catalogs.forEach(catalog => {
  console.log(`Catalog: ${catalog.name} (Provider: ${catalog.from})`);
});

Related APIs

• Datasets API - List datasets from configured data sources
• Models API - List available AI models
• HTTP Query API - Execute SQL queries across catalogs