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

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, 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 – 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 – Defines the plugin-side API used by database-specific extensions.
• spec/code/server/java-object-converter-contracts.md – Documents JSON marshalling rules and object conversion logic.
• spec/code/server/java-interface-contracts.md – Outlines high-level service interfaces exposed to the web layer.
• spec/code/server/java-impl-contracts.md – Specifies implementation expectations for service layer classes.
• 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. 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:

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:

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

Execute a SQL statement against a specific datasource:

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:

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 file documents the SPI (Service Provider Interface) that database-specific plugins implement, while java-interface-contracts.md and 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 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), object conversion (java-object-converter-contracts.md), and implementation details (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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}