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

> Easily access self-hosted Akash Console API documentation. Learn how to find OpenAPI JSON specs at /v1/doc and interactive Swagger UI at /v1/swagger for seamless integration.

- Repository: [Akash Network/console](https://github.com/akash-network/console)
- Tags: api-reference
- Published: 2026-02-24

---

**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

```bash
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:

```bash
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:

```bash
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:

```typescript
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`](https://github.com/akash-network/console/blob/main/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`](https://github.com/akash-network/console/blob/main/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`](https://github.com/akash-network/console/blob/main/apps/api/src/rest-app.ts) — Registers the public `/v1/doc` and `/v1/swagger` endpoints.
- [`apps/api/src/routers/internalRouter.ts`](https://github.com/akash-network/console/blob/main/apps/api/src/routers/internalRouter.ts) — Registers the internal `/internal/doc` and `/internal/swagger` endpoints.
- [`apps/api/src/routers/deploymentApiRouter.ts`](https://github.com/akash-network/console/blob/main/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`](https://github.com/akash-network/console/blob/main/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.