> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiql.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Install and use the AiQL Python client.

The Python SDK wraps the AiQL API for Python 3.10 and later.

## Prerequisites

* Python 3.10 or later
* An AiQL API key from the [Dashboard](https://app.aiql.io)

## Install

<CodeGroup>
  ```bash pip theme={null}
  pip install aiql
  ```

  ```bash uv theme={null}
  uv add aiql
  ```

  ```bash poetry theme={null}
  poetry add aiql
  ```
</CodeGroup>

## Authenticate

Create a client with your API key. Read the key from an environment variable instead of hardcoding it.

```python theme={null}
import os
from aiql import AiQL

client = AiQL(api_key=os.environ["AIQL_API_KEY"])
```

To target a different environment, set the base URL. Pass `workspace_id` on the client to send it as the `AiQL-Workspace` header on every workspace-scoped call.

```python theme={null}
client = AiQL(
    api_key=os.environ["AIQL_API_KEY"],
    base_url="http://127.0.0.1:8000",
    workspace_id="ws_3a1b",
)
```

## Workspaces

```python theme={null}
workspace = client.workspaces.create(name="Analytics")

workspaces = client.workspaces.list()

workspace = client.workspaces.get(workspace.id)

workspace = client.workspaces.update(workspace.id, name="Analytics EU")

client.workspaces.delete(workspace.id)
```

## Ingestions

```python theme={null}
ingestion = client.ingestions.create(
    workspace_id=workspace.id,
    url="https://example.com/report.pdf",
    metadata={"customerId": "abc"},
)

ingestion = client.ingestions.get(ingestion.id)

client.ingestions.cancel(ingestion.id)

client.ingestions.retry(ingestion.id)
```

## Queries

```python theme={null}
query = client.queries.create(
    workspace_id=workspace.id,
    content="count events grouped by day",
)

result = client.queries.get(query.id)
```

## Sources

```python theme={null}
chunks = client.sources.chunks(ingestion.id, workspace_id=workspace.id)

graph = client.sources.graph(ingestion.id, workspace_id=workspace.id)
```

## Tools

```python theme={null}
markdown = client.tools.convert(url="https://example.com/report.pdf")

chunks = client.tools.split(markdown=markdown)

schema = client.tools.shape(markdown=markdown)

records = client.tools.extract(markdown=markdown, schema=schema)
```

## Error handling

The SDK raises `AiqlError` for failed requests. Inspect `status_code` and `detail` to handle specific cases.

```python theme={null}
from aiql import AiQL, AiqlError

client = AiQL(api_key=os.environ["AIQL_API_KEY"])

try:
    client.queries.get("missing-id")
except AiqlError as error:
    print(error.status_code, error.detail)
```