# Where to Find Chat2DB API Documentation: Complete Guide to REST Endpoints and OpenAPI Specs

> Find Chat2DB API documentation easily. Access REST endpoint details and OpenAPI specs from the OtterMind/Chat2DB repository. Your complete guide to Chat2DB API.

- Repository: [OtterMind/Chat2DB](https://github.com/OtterMind/Chat2DB)
- Tags: api-reference
- Published: 2026-07-27

---

**Chat2DB API documentation is maintained as version-controlled Markdown contract files in the `spec/code/server/` directory, with the primary REST API specification defined in [`java-web-controller-contracts.md`](https://github.com/OtterMind/Chat2DB/blob/main/java-web-controller-contracts.md), and a runtime OpenAPI endpoint available at `/v3/api-docs` when the server runs on the default community port 10825.**

The OtterMind/Chat2DB repository stores its complete API specification as code in the `spec/` directory rather than traditional external documentation sites. This approach ensures the documentation remains synchronized with implementation changes. The contracts cover everything from HTTP endpoints to internal service boundaries and plugin interfaces.

## Locating the Static API Contract Files

The definitive source for Chat2DB’s API structure lives in the `spec/code/server/` path. These Markdown files describe the complete contract stack from web controllers down to implementation details.

- **[`spec/code/server/java-web-controller-contracts.md`](https://github.com/OtterMind/Chat2DB/blob/main/spec/code/server/java-web-controller-contracts.md)** – Contains every REST path (e.g., `/api/v1/datasource/*`, `/api/v1/sql/execute`) with detailed request and response DTOs.
- **[`spec/code/server/java-plugin-contracts.md`](https://github.com/OtterMind/Chat2DB/blob/main/spec/code/server/java-plugin-contracts.md)** – Defines the plugin-side API used by database-specific extensions.
- **[`spec/code/server/java-object-converter-contracts.md`](https://github.com/OtterMind/Chat2DB/blob/main/spec/code/server/java-object-converter-contracts.md)** – Documents JSON marshalling rules and object conversion logic.
- **[`spec/code/server/java-interface-contracts.md`](https://github.com/OtterMind/Chat2DB/blob/main/spec/code/server/java-interface-contracts.md)** – Outlines high-level service interfaces exposed to the web layer.
- **[`spec/code/server/java-impl-contracts.md`](https://github.com/OtterMind/Chat2DB/blob/main/spec/code/server/java-impl-contracts.md)** – Specifies implementation expectations for service layer classes.
- **[`spec/code/server/java-module-boundaries.md`](https://github.com/OtterMind/Chat2DB/blob/main/spec/code/server/java-module-boundaries.md)** – Describes module responsibilities and API exposure boundaries.

You can view these files directly on GitHub at the paths above, or clone the repository to browse them locally.

## Understanding the REST Controller Contracts

The primary entry point for understanding Chat2DB’s REST API is [`java-web-controller-contracts.md`](https://github.com/OtterMind/Chat2DB/blob/main/java-web-controller-contracts.md). According to the source code analysis, this file maps every public HTTP endpoint to its corresponding data transfer objects.

Key endpoint patterns documented include:
- **`/api/v1/datasource/list`** – Retrieves configured database connections
- **`/api/v1/sql/execute`** – Executes SQL statements against specified datasources

Each entry specifies the HTTP method, path parameters, request body schemas, and response models. This serves as the authoritative reference for building API clients or integrations.

## Runtime OpenAPI Specification

When running Chat2DB, the application generates a live OpenAPI (Swagger) specification accessible at:

```bash
http://<host>:10825/v3/api-docs

```

The default **community edition port is 10825**. This runtime specification reflects the actual deployed version’s endpoints, which may include additional endpoints beyond the static contract files depending on active plugins or configuration.

To explore the API interactively, point Swagger-UI or Postman to this endpoint, or use it for automated client generation.

## Practical API Usage Examples

The following examples demonstrate how to interact with the Chat2DB REST API using `curl`.

Retrieve a list of all configured data sources:

```bash
curl -H "Authorization: Bearer <your-token>" \
     http://127.0.0.1:10825/api/v1/datasource/list

```

Execute a SQL statement against a specific datasource:

```bash
curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <your-token>" \
     -d '{"datasourceId":1,"sql":"SELECT * FROM users LIMIT 10"}' \
     http://127.0.0.1:10825/api/v1/sql/execute

```

Fetch the OpenAPI JSON specification for client SDK generation:

```bash
curl http://127.0.0.1:10825/v3/api-docs > chat2db-openapi.json

```

## Plugin and Service Layer Contracts

Beyond the web-facing REST API, Chat2DB maintains detailed contracts for internal service boundaries. The **[`java-plugin-contracts.md`](https://github.com/OtterMind/Chat2DB/blob/main/java-plugin-contracts.md)** file documents the SPI (Service Provider Interface) that database-specific plugins implement, while **[`java-interface-contracts.md`](https://github.com/OtterMind/Chat2DB/blob/main/java-interface-contracts.md)** and **[`java-impl-contracts.md`](https://github.com/OtterMind/Chat2DB/blob/main/java-impl-contracts.md)** define the hexagonal architecture boundaries between the web layer and business logic.

These files are essential for contributors extending Chat2DB with new database drivers or modifying core service implementations.

## Summary

- **Primary documentation** resides in [`spec/code/server/java-web-controller-contracts.md`](https://github.com/OtterMind/Chat2DB/blob/main/spec/code/server/java-web-controller-contracts.md) within the OtterMind/Chat2DB repository.
- **Runtime discovery** is available via the OpenAPI endpoint at `/v3/api-docs` on port 10825 (community edition).
- **Supporting contracts** cover plugins ([`java-plugin-contracts.md`](https://github.com/OtterMind/Chat2DB/blob/main/java-plugin-contracts.md)), object conversion ([`java-object-converter-contracts.md`](https://github.com/OtterMind/Chat2DB/blob/main/java-object-converter-contracts.md)), and implementation details ([`java-impl-contracts.md`](https://github.com/OtterMind/Chat2DB/blob/main/java-impl-contracts.md)).
- **Authentication** uses Bearer tokens for protected endpoints like datasource listing and SQL execution.

## Frequently Asked Questions

### Where is the Chat2DB REST API documented?

The Chat2DB REST API is documented in the [`spec/code/server/java-web-controller-contracts.md`](https://github.com/OtterMind/Chat2DB/blob/main/spec/code/server/java-web-controller-contracts.md) file in the repository, which lists every endpoint path, request DTO, and response model. Additionally, a runtime OpenAPI specification is served at `/v3/api-docs` when the application is running.

### What port does Chat2DB use for API documentation?

The Chat2DB community edition serves its OpenAPI documentation and REST endpoints on **port 10825** by default. You can access the JSON specification at `http://127.0.0.1:10825/v3/api-docs` and individual API endpoints under `http://127.0.0.1:10825/api/v1/`.

### How do I generate a client SDK for Chat2DB?

Download the OpenAPI specification from the runtime endpoint using `curl http://localhost:10825/v3/api-docs > chat2db-openapi.json`, then feed this JSON file into any OpenAPI generator tool (such as Swagger Codegen or OpenAPI Generator) to produce client libraries in Java, Python, TypeScript, or other supported languages.

### Are the Chat2DB API contracts version controlled?

Yes, all API contracts are version-controlled Markdown files stored in the `spec/code/server/` directory of the OtterMind/Chat2DB repository. As the API evolves, these contract files are updated alongside the implementation code, ensuring documentation remains the single source of truth.