API Introduction

Learn how to programmatically manage your Dokploy instance using the tRPC-based API

The Dokploy API allows you to programmatically manage all aspects of your self-hosted Platform as a Service. Deploy applications, manage databases, configure domains, and orchestrate your entire infrastructure through a powerful API built on tRPC.

Base URL

All API requests should be made to your Dokploy instance:

https://your-dokploy-instance.com/api/trpc

Replace your-dokploy-instance.com with your actual Dokploy domain.

API Architecture

Dokploy uses tRPC (TypeScript Remote Procedure Call) as its API framework. tRPC provides end-to-end type safety and eliminates the need for traditional REST endpoints or GraphQL schemas.

Key Characteristics

• Type-safe: Full TypeScript support with automatic type inference
• Procedure-based: APIs are organized into routers with procedures instead of traditional REST endpoints
• Real-time: Built-in support for subscriptions and WebSocket connections
• Validation: Automatic request/response validation using Zod schemas

API Format

All tRPC requests follow this pattern:

POST /api/trpc/{router}.{procedure}

For example:

• project.create - Create a new project
• application.deploy - Deploy an application
• docker.getContainers - Get Docker containers

Available API Routers

The Dokploy API is organized into the following routers:

Router	Description
admin	System administration and monitoring setup
application	Manage applications and deployments
backup	Backup and restore operations
certificates	SSL/TLS certificate management
compose	Docker Compose services
deployment	Deployment history and logs
docker	Docker container operations
domain	Domain and DNS configuration
environment	Environment management
mariadb	MariaDB database services
mongo	MongoDB database services
mysql	MySQL database services
postgres	PostgreSQL database services
project	Project management
redis	Redis database services
registry	Docker registry configuration
security	Basic authentication for applications
server	Server management
settings	Dokploy instance settings
user	User and API key management

Request Format

Query Procedures (GET)

For query procedures, parameters are sent as URL query parameters:

GET /api/trpc/project.one?input={"projectId":"abc123"}

Mutation Procedures (POST)

For mutation procedures, parameters are sent in the request body:

POST /api/trpc/project.create
Content-Type: application/json

{
  "name": "My Project",
  "description": "A new project",
  "env": "production"
}

Response Format

All successful API responses follow this structure:

{
  "result": {
    "data": {
      // Response data here
    }
  }
}

Success Response Example

{
  "result": {
    "data": {
      "id": "proj_abc123",
      "name": "My Project",
      "description": "A new project",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  }
}

Error Response Example

{
  "error": {
    "message": "Project not found",
    "code": "NOT_FOUND",
    "data": {
      "code": "NOT_FOUND",
      "httpStatus": 404,
      "path": "project.one"
    }
  }
}

Error Codes

The API uses standard tRPC error codes:

Code	HTTP Status	Description
BAD_REQUEST	400	Invalid request parameters
UNAUTHORIZED	401	Missing or invalid authentication
FORBIDDEN	403	Insufficient permissions
NOT_FOUND	404	Resource not found
TIMEOUT	408	Request timeout
CONFLICT	409	Resource conflict
PRECONDITION_FAILED	412	Precondition failed
PAYLOAD_TOO_LARGE	413	Request payload too large
INTERNAL_SERVER_ERROR	500	Server error

Rate Limiting

API keys can be configured with rate limiting to control API usage. When creating an API key, you can set:

• Rate limit window: Time window in milliseconds
• Maximum requests: Maximum requests allowed in the time window
• Request limits: Remaining requests with refill intervals

If you exceed the rate limit, you’ll receive a 429 TOO_MANY_REQUESTS error:

{
  "error": {
    "message": "Rate limit exceeded",
    "code": "TOO_MANY_REQUESTS"
  }
}

OpenAPI Specification

Dokploy provides an OpenAPI 3.0 specification for API documentation and client generation. The OpenAPI spec is available at:

https://your-dokploy-instance.com/api/openapi.json

You can use this specification with tools like:

• Swagger UI: Interactive API documentation
• Postman: Import and test API endpoints
• OpenAPI Generator: Generate client libraries

Next Steps

Authentication

Learn how to authenticate API requests using API keys

Projects

Create and manage projects

Applications

Deploy and manage applications

Databases

Manage database services