## 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](https://github.com/spicehq/docs/blob/trunk/api/sql-query/http-api.md)   |
| SQL (Arrow Flight)    | `grpc+tls://flight.spiceai.io`                | Password in handshake  | [Arrow Flight API](https://github.com/spicehq/docs/blob/trunk/api/sql-query/apache-arrow-flight-api.md) |
| LLM Chat              | `https://data.spiceai.io/v1/chat/completions` | `X-API-Key` header    | [LLM API](https://github.com/spicehq/docs/blob/trunk/api/openai-api.md)       |
| Search                | `https://data.spiceai.io/v1/search`           | `X-API-Key` header    | [Search API](https://github.com/spicehq/docs/blob/trunk/api/search.md)       |
| Health                | `https://data.spiceai.io/health`              | None                  | [Health API](https://github.com/spicehq/docs/blob/trunk/api/health.md)       |

### 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](https://github.com/spicehq/docs/blob/trunk/api/management/apps.md)             |
| Deployments | [Deployments API](https://github.com/spicehq/docs/blob/trunk/api/management/deployments.md) |
| API Keys    | [API Keys API](https://github.com/spicehq/docs/blob/trunk/api/management/api-keys.md)      |
| Secrets     | [Secrets API](https://github.com/spicehq/docs/blob/trunk/api/management/secrets.md)       |
| Members     | [Members API](https://github.com/spicehq/docs/blob/trunk/api/management/members.md)       |

See the full [Management API reference](https://github.com/spicehq/docs/blob/trunk/api/management/README.md).

## SDKs

Official SDKs handle authentication, serialization, and connection management for you.

| Language   | Package              | Documentation                                                             |
|------------|---------------------|--------------------------------------------------------------------------|
| Python     | `spicepy`           | [Python SDK](https://github.com/spicehq/docs/blob/trunk/sdks/python-sdk/README.md)          |
| Node.js    | `@spiceai/spiceai`  | [Node.js SDK](https://github.com/spicehq/docs/blob/trunk/sdks/node.js-sdk)                  |
| Go         | `github.com/spiceai/gospice` | [Go SDK](https://github.com/spicehq/docs/blob/trunk/sdks/go.md)                        |
| Rust       | `spiceai`           | [Rust SDK](https://github.com/spicehq/docs/blob/trunk/sdks/rust-sdk/README.md)          |
| Java       | [Java SDK](https://github.com/spicehq/docs/blob/trunk/sdks/java-sdk.md)                 |
| .NET       | [Dotnet SDK](https://github.com/spicehq/docs/blob/trunk/sdks/dotnet-sdk.md)              |

### Quick example (Python)

Copy

```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

Copy

```sql
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:

Copy

```python
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](https://github.com/spicehq/docs/blob/trunk/features/data-acceleration/README.md) 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:

Copy

```bash
# 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](https://github.com/spicehq/docs/blob/trunk/portal/profile/personal-access-tokens.md).