For the complete documentation index, see [llms.txt](https://docs.spice.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.spice.ai/help/apis-and-sdks.md).

# 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](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)

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

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

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

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