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

# API Reference

> OpenAI-compatible RESTful API

## Authentication

All API requests need to carry the API Key in the header:

```text theme={null}
Authorization: Bearer YOUR_API_KEY
```

API Keys can be created and managed in Workspace Settings → API Key Management.

## Base URL

| Environment        | Base URL                   |
| ------------------ | -------------------------- |
| Cloud SaaS         | `https://api.zgi.cn/v1`    |
| Private deployment | `http://YOUR_HOST:2678/v1` |

## Core endpoint

* `POST /v1/chat/completions`: Send conversation request, support knowledge base retrieval and streaming output

* `GET /v1/models`: Get the list of available models

* `POST /v1/workflows/{workflow_id}/run`: triggers the execution of the specified workflow

* `POST /v1/knowledge-bases/{kb_id}/documents`: Upload documents to the knowledge base

* `POST /v1/knowledge-bases/{kb_id}/search`: Query knowledge base search results

## Dialog request example

```bash theme={null}
curl -X POST https://api.zgi.cn/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "zgi-default",
    "messages": [
      { "role": "system", "content": "You are a contract review assistant" },
      { "role": "user", "content": "What are the payment terms in this contract?" }
    ],
    "knowledge_base_id": "kb_xxxxxx",
    "stream": true,
    "temperature": 0.7
  }'
```

## Request parameters

| Parameters          | Type    | Required | Description                        |
| ------------------- | ------- | -------- | ---------------------------------- |
| `model`             | string  | required | Model ID to use                    |
| `messages`          | array   | required | array of conversation messages     |
| `knowledge_base_id` | string  | Optional | The associated knowledge base ID   |
| `stream`            | boolean | Optional | Whether to enable streaming output |
| `temperature`       | float   | optional | sampling temperature (0-2)         |

## SDK

```bash theme={null}
# Python
pip install zgi-sdk

# JavaScript / TypeScript
npm install @zgi/sdk
```

```python theme={null}
from zgi import ZGIClient

client = ZGIClient(api_key="YOUR_API_KEY")

# Query knowledge base
result = client.knowledge.query(
    knowledge_base_id="kb_xxxxxx",
    question="How many days is the payment cycle in this contract?"
)
print(result.answer)
print(result.citations)  # [{"source": "contract.pdf", "page": 4, "text": "..."}]

# trigger workflow
run = client.workflows.run(
    workflow_id="wf_xxxxxx",
    inputs={"document_url": "https://..."}
)
```