How to Access the API Documentation for Akash Console: OpenAPI Endpoints Explained

The Akash Console API server exposes auto-generated OpenAPI 3.0 documentation via dedicated HTTP endpoints, allowing you to retrieve raw JSON specs at /v1/doc and browse interactive Swagger UI at /v1/swagger.

The akash-network/console repository provides a comprehensive REST API for managing cloud deployments on the Akash Network. Understanding how to access the API documentation for Akash Console is essential for developers integrating with the platform, as it offers complete visibility into available endpoints, request schemas, and authentication requirements.

Available API Documentation Endpoints

When the API server (apps/api) is running, it exposes multiple documentation endpoints serving different API scopes. Each endpoint provides both a raw OpenAPI JSON document and an interactive Swagger UI interface.

• GET /v1/doc — Returns the raw OpenAPI JSON document for public console APIs. Append ?scope=console to filter specifically for console routes.
• GET /v1/swagger — Serves the interactive Swagger UI page that consumes the JSON from /v1/doc.
• GET /internal/doc — Returns the OpenAPI document scoped for internal admin routes.
• GET /internal/swagger — Provides the Swagger UI for internal administrative APIs.
• GET /deployments/doc — Returns the OpenAPI specification for the deployment-specific API.
• GET /deployments/swagger — Serves the Swagger UI for deployment management endpoints.

All endpoints are available on the API server port (default 3000) when running locally.

Retrieving the Raw OpenAPI Specification

To programmatically access the API documentation for Akash Console, fetch the raw OpenAPI JSON using standard HTTP tools. This is useful for generating clients, validation, or offline documentation.

Using curl to fetch the public API spec

curl -s http://localhost:3000/v1/doc?scope=console | jq .

The response is a complete OpenAPI 3.0 specification object containing all public routes, request/response schemas defined with Zod, and security definitions.

Accessing internal admin documentation

For administrative endpoints, use the internal scope:

curl http://localhost:3000/internal/doc | jq .

Interactive Swagger UI Access

For manual exploration and testing, the Akash Console serves a browser-based Swagger UI that renders the documentation interactively.

To access the UI:

1. Start the API server using pnpm dev:api or docker compose up api.
2. Navigate to http://localhost:3000/v1/swagger in your browser.

The interface displays all available endpoints, example request payloads, response schemas, and allows you to execute API calls directly against the running server.

Programmatic Client Generation

You can generate type-safe API clients directly from the live documentation endpoints using tools like openapi-typescript.

Generate a typed TypeScript client:

npx openapi-typescript http://localhost:3000/v1/doc?scope=console -o src/api-client.ts

Import the generated types in your application to ensure compile-time safety when calling Akash Console endpoints:

import { paths } from './api-client.ts';
// Use paths for fully-typed API operations

How the Documentation Is Generated

According to the akash-network/console source code, the documentation is generated automatically from Hono routes using @hono/zod-openapi.

In apps/api/src/core/services/openapi-docs/openapi-docs.service.ts, the OpenApiDocsService aggregates route metadata from all registered routers. Individual route files, such as apps/api/src/provider/routes/providers/providers.router.ts, declare endpoint definitions using router.openapi(...), specifying request/response schemas and security requirements.

The central aggregation happens in:

• apps/api/src/rest-app.ts — Registers the public /v1/doc and /v1/swagger endpoints.
• apps/api/src/routers/internalRouter.ts — Registers the internal /internal/doc and /internal/swagger endpoints.
• apps/api/src/routers/deploymentApiRouter.ts — Provides /deployments/doc and /deployments/swagger for deployment-specific routes.

This architecture ensures the documentation always reflects the current API implementation without manual updates.

Summary

• Access raw OpenAPI 3.0 JSON at /v1/doc (public) or /internal/doc (admin) when the API server is running.
• Browse interactive documentation at /v1/swagger and /internal/swagger for visual endpoint exploration.
• Filter documentation scope using query parameters like ?scope=console or ?scope=internal.
• Generate type-safe clients using openapi-typescript pointing to the live /v1/doc endpoint.
• Documentation is auto-generated from Zod schemas in Hono routes via OpenApiDocsService located in apps/api/src/core/services/openapi-docs/.

Frequently Asked Questions

What is the difference between /v1/doc and /v1/swagger?

The /v1/doc endpoint returns the raw OpenAPI 3.0 JSON specification, while /v1/swagger serves an HTML page rendering the interactive Swagger UI that consumes that JSON. Use /v1/doc for programmatic access and client generation, and /v1/swagger for manual browsing and testing in a web browser.

How do I access the internal admin API documentation?

Navigate to http://localhost:3000/internal/swagger for the interactive UI, or http://localhost:3000/internal/doc for the raw JSON. These endpoints expose administrative routes separate from the public console APIs, as registered in apps/api/src/routers/internalRouter.ts.

Can I generate a TypeScript client from the Akash Console API documentation?

Yes. Use openapi-typescript or similar tools to point at the live documentation endpoint: npx openapi-typescript http://localhost:3000/v1/doc?scope=console -o client.ts. This generates fully-typed paths and components based on the Zod schemas defined in the Hono routes.

Do I need authentication to view the API documentation?

No authentication is required to view the OpenAPI documentation endpoints (/v1/doc, /v1/swagger, etc.) when running the server locally. However, executing actual API calls through the Swagger UI or generated clients requires appropriate authentication tokens as defined in the security schemes of the specification.

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