apis and sdks.md
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to page URLs; this page is available as Markdown.
APIs & SDKs
API Endpoints
Spice.ai exposes two sets of APIs: runtime APIs (for querying data and AI) and the Management API (for managing apps and infrastructure).
Runtime APIs
| API | Endpoint | Auth | Documentation |
|---|---|---|---|
| SQL (HTTP) | https://data.spiceai.io/v1/sql |
X-API-Key header |
HTTP API |
| SQL (Arrow Flight) | grpc+tls://flight.spiceai.io |
Password in handshake | Arrow Flight API |
| LLM Chat | https://data.spiceai.io/v1/chat/completions |
X-API-Key header |
LLM API |
| Search | https://data.spiceai.io/v1/search |
X-API-Key header |
Search API |
| Health | https://data.spiceai.io/health |
None | Health API |
Management API
The Management API at https://api.spice.ai/v1/ uses personal access tokens or OAuth tokens (not app API keys).
| Endpoint | Documentation |
|---|---|
| Apps | Apps API |
| Deployments | Deployments API |
| API Keys | API Keys API |
| Secrets | Secrets API |
| Members | Members API |
See the full Management API reference.
SDKs
Official SDKs handle authentication, serialization, and connection management for you.
| Language | Package | Documentation |
|---|---|---|
| Python | spicepy |
Python SDK |
| Node.js | @spiceai/spiceai |
Node.js SDK |
| Go | github.com/spiceai/gospice |
Go SDK |
| Rust | spiceai |
Rust SDK |
| Java | Java SDK | |
| .NET | Dotnet SDK |
Quick example (Python)
from spicepy import Client
client = Client("YOUR_API_KEY")
reader = client.query("SELECT * FROM my_table LIMIT 10")
df = reader.read_pandas()
print(df)
Choosing HTTP vs. Arrow Flight
| HTTP API | Arrow Flight API | |
|---|---|---|
| Format | JSON | Apache Arrow (binary) |
| Best for | Simple queries, small results | Large datasets, production workloads |
| Row limits | Yes | No |
| Streaming | No | Yes |
| Performance | Good | Best |
| SDK support | All SDKs | All SDKs |
Recommendation: Use Arrow Flight (via SDKs) for production workloads and large result sets. Use the HTTP API for quick testing, small queries, or REST-based integrations.
Query Best Practices
Use LIMIT and OFFSET for large results
SELECT * FROM my_table
ORDER BY id
LIMIT 1000 OFFSET 0
Increment OFFSET to page through results. Always include ORDER BY for deterministic pagination.
Use recent tables for near-real-time data
Recent tables provide fast access to the last ~30 minutes of data, ideal for dashboards and monitoring.
Combine SQL with client-side processing
Use SQL for filtering, aggregation, and joins, then use client libraries (pandas, NumPy, etc.) for further processing:
reader = client.query("SELECT date, value FROM metrics WHERE date > '2025-01-01'")
df = reader.read_pandas()
df['rolling_avg'] = df['value'].rolling(7).mean()
Use data acceleration for repeated queries
Enable data acceleration on frequently queried datasets to avoid hitting the source on every request.
Common Issues
Arrow Flight TLS errors
Set the GRPC_DEFAULT_SSL_ROOTS_FILE_PATH environment variable:
# macOS
export GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=/etc/ssl/cert.pem
HTTP API returns truncated results
The HTTP API has built-in row and timeout limits. Switch to Arrow Flight or an SDK for unlimited streaming results.
Management API returns 401
The Management API uses personal access tokens, not app API keys. Generate a token under Profile → Personal Access Tokens.