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

## Further Reading

* [SQL Query API](https://github.com/spicehq/docs/blob/trunk/api/sql-query/README.md)
* [LLM API](https://github.com/spicehq/docs/blob/trunk/api/openai-api.md)
* [Search API](https://github.com/spicehq/docs/blob/trunk/api/search.md)
* [Best Practices](https://github.com/spicehq/docs/blob/trunk/best-practices.md)
* [SQL Reference](https://github.com/spicehq/docs/blob/trunk/reference/sql-reference.md)
* [Arrow Flight Samples](https://github.com/spicehq/docs/blob/trunk/reference/arrow-flight-samples.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.spice.ai/help/apis-and-sdks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.