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

# Overview

> Authentication, base URL, and scoping for the Polyvia REST API

The Polyvia REST API lets you upload documents, organise them into groups, ask natural-language questions across your workspace, and monitor usage. This page covers authentication, the base URL, and workspace scoping; the pages that follow document each endpoint.

<Tip>
  The [Python SDK](/products/python-sdk) (`pip install polyvia`) wraps every endpoint with a typed client and adds first-class support for the MCP server and agent frameworks.
</Tip>

## Authentication

All API requests require authentication using an API key. Include your key in the `Authorization` header:

```bash theme={null}
Authorization: Bearer poly_<your-key>
```

<Card title="How to get an API key" icon="key" href="/get-api-key" horizontal>
  Create, use, and manage your key — and how workspace binding works.
</Card>

## Workspace Scoping

Each API key is bound to **one workspace** at the moment you create it — either your personal workspace or a specific organization. Every request made with that key reads and writes only that workspace's data; the key cannot reach across workspaces.

* Mint a key while you're in your **personal workspace** → it sees personal documents, groups, and chats only.
* Mint a key while you're in an **organization** → it sees that org's shared documents and groups. Any teammate's API key minted in the same org reads the same data.

To work across multiple workspaces from the same script, switch workspace and create a separate key for each (on the **API** page). Use the appropriate key per request.

<Note>
  Switching your *active* workspace in the UI later does not change what an existing key can access. The binding is permanent — revoke and re-mint to change scope.
</Note>

## Base URL

```
https://app.polyvia.ai
```

All endpoints are prefixed with `/api/v1`.

## Quick Start

Here's a complete example: ingest a document and query for insights.

<CodeGroup>
  ```python Python theme={null}
  import httpx
  import time

  API_KEY = "poly_<your-key>"
  BASE    = "https://app.polyvia.ai"
  HEADERS = {"Authorization": f"Bearer {API_KEY}"}

  # 1. Upload
  with open("report.pdf", "rb") as f:
      resp = httpx.post(
          f"{BASE}/api/v1/ingest",
          headers=HEADERS,
          files={"file": ("report.pdf", f, "application/pdf")},
          data={"name": "Q4 Report"},
      )
  resp.raise_for_status()
  task_id     = resp.json()["task_id"]
  document_id = resp.json()["document_id"]

  # 2. Poll until ingestion completes
  while True:
      status = httpx.get(f"{BASE}/api/v1/ingest/{task_id}", headers=HEADERS).json()["status"]
      print(f"Status: {status}")
      if status in ("completed", "failed"):
          break
      time.sleep(5)

  # 3. Query
  answer = httpx.post(
      f"{BASE}/api/v1/query",
      headers=HEADERS,
      json={"query": "What are the key findings?", "document_id": document_id},
  ).json()["answer"]

  print(answer)
  ```

  ```bash cURL theme={null}
  # 1. Upload
  curl -X POST https://app.polyvia.ai/api/v1/ingest \
    -H "Authorization: Bearer poly_<your-key>" \
    -F "file=@/path/to/report.pdf" \
    -F "name=Q4 Report"

  # 2. Check status (replace TASK_ID)
  curl https://app.polyvia.ai/api/v1/ingest/TASK_ID \
    -H "Authorization: Bearer poly_<your-key>"

  # 3. Query
  curl -X POST https://app.polyvia.ai/api/v1/query \
    -H "Authorization: Bearer poly_<your-key>" \
    -H "Content-Type: application/json" \
    -d '{"query": "What are the key findings?", "document_id": "DOCUMENT_ID"}'
  ```
</CodeGroup>

## Support

Need help? Reach out to our team:

* **Email**: [mgierlach5@gmail.com](mailto:mgierlach5@gmail.com)
* **Platform**: [Polyvia Platform](/products/platform)