{"slug":"api-overview","title":"API Overview","description":"DanubeData provides a comprehensive RESTful API that allows you to programmatically manage all your infrastructure resources.","section":"API Reference","url":"https://docs.danubedata.ro/api-overview","markdown_url":"https://docs.danubedata.ro/api-overview.md","breadcrumbs":[{"title":"API Reference","slug":null},{"title":"API Overview","slug":"api-overview"}],"headings":[{"level":1,"title":"API Overview","id":"api-overview"},{"level":2,"title":"Interactive API Documentation","id":"interactive-api-documentation"},{"level":2,"title":"Quick Start","id":"quick-start"},{"level":3,"title":"1. Get Your API Token","id":"1-get-your-api-token"},{"level":3,"title":"2. Make Your First Request","id":"2-make-your-first-request"},{"level":3,"title":"3. Explore the Documentation","id":"3-explore-the-documentation"},{"level":2,"title":"API Base URL","id":"api-base-url"},{"level":2,"title":"Authentication","id":"authentication"},{"level":2,"title":"Available Resources","id":"available-resources"},{"level":3,"title":"Infrastructure","id":"infrastructure"},{"level":3,"title":"Applications","id":"applications"},{"level":3,"title":"Storage","id":"storage"},{"level":3,"title":"Networking","id":"networking"},{"level":3,"title":"Operations","id":"operations"},{"level":2,"title":"Connection Endpoints","id":"connection-endpoints"},{"level":2,"title":"Response Format","id":"response-format"},{"level":2,"title":"API Token Permissions","id":"api-token-permissions"},{"level":3,"title":"Available Scopes","id":"available-scopes"},{"level":3,"title":"Permission Mapping","id":"permission-mapping"},{"level":3,"title":"Default Permissions","id":"default-permissions"},{"level":3,"title":"Predefined Roles","id":"predefined-roles"},{"level":2,"title":"Rate Limiting","id":"rate-limiting"},{"level":2,"title":"Error Handling","id":"error-handling"},{"level":2,"title":"SDK and Client Libraries","id":"sdk-and-client-libraries"},{"level":2,"title":"Next Steps","id":"next-steps"},{"level":2,"title":"Need Help?","id":"need-help"}],"format":"markdown","word_count":1266,"content":"# API Overview\n\nDanubeData provides a comprehensive RESTful API that allows you to programmatically manage all your infrastructure resources.\n\n## Interactive API Documentation\n\nOur interactive API documentation is available at: **`/docs/api`**\n\nYou can access it directly by visiting:\n- **Production:** `https://danubedata.ro/docs/api`\n\nOur interactive API documentation provides:\n\n- **Complete endpoint reference** for all API v1 operations\n- **Try It functionality** - test endpoints directly in your browser\n- **Request/response examples** for every endpoint\n- **Authentication testing** with your API tokens\n- **OpenAPI 3.0 specification** for integration tools\n\n## Quick Start\n\n### 1. Get Your API Token\n\n1. Navigate to **API Tokens** in your account settings\n2. Click **Create New Token**\n3. Give it a descriptive name\n4. Select the appropriate permissions\n5. Choose the project scope — **This project only** (default) or **All my projects**\n6. Copy the token (shown only once)\n\n### 2. Make Your First Request\n\n```bash\ncurl -H \"Authorization: Bearer YOUR_TOKEN_HERE\" \\\n     https://danubedata.ro/api/v1/vps\n```\n\n**Note**: Ensure your API token has the appropriate permissions (e.g., `vps:read`) for the endpoints you want to access.\n\n### 3. Explore the Documentation\n\nVisit `/docs/api` to:\n- Browse all available endpoints\n- See detailed request/response formats\n- Test endpoints with your token\n- Download the OpenAPI specification\n\n## API Base URL\n\n```\nProduction: https://danubedata.ro/api/v1\n```\n\nAll API requests should be made to this base URL followed by the specific endpoint path.\n\n## Authentication\n\nAll API requests require authentication using a bearer token:\n\n```\nAuthorization: Bearer YOUR_TOKEN_HERE\n```\n\nLearn more about authentication in the [Authentication Guide](https://docs.danubedata.ro/api-authentication).\n\n## Available Resources\n\nThe API provides access to manage:\n\n### Infrastructure\n- **VPS Instances** - Create and manage virtual private servers\n- **Database Instances** - PostgreSQL, MySQL, and MariaDB databases (with read replicas)\n- **Cache Instances** - Redis, Valkey, and Dragonfly in-memory stores\n- **Queue Instances** - managed RabbitMQ message brokers\n- **Parameter Groups** - reusable database/cache configuration presets\n\n### Applications\n- **Serverless Containers** - deploy and manage scale-to-zero containers\n- **Static Sites** - managed static site hosting with custom domains\n\n### Storage\n- **Object Storage** - S3-compatible storage buckets\n- **Access Keys** - S3 credentials management\n\n### Networking\n- **Firewalls** - Configure security rules\n- **SSH Keys** - Manage access credentials\n\n### Operations\n- **Snapshots** - Backup and restore operations\n- **Webhooks** - Event notifications\n- **Metrics** - Resource monitoring\n\n## Connection Endpoints\n\nDatabase and cache instances expose two different ports, and mixing them up\nproduces an endpoint that does not work:\n\nEvery instance has a **private** endpoint. Enabling public DNS adds a second,\n**public** one; it never replaces the private one.\n\n| Field | Plane | Meaning |\n|---|---|---|\n| `internal_host` / `internal_port` / `internal_endpoint` | Private | The in-cluster Service on the engine port. Always present, never changes when you enable or disable public DNS. |\n| `dns_hostname` / `dns_port` / `public_endpoint` | Public | The DNS hostname and the port allocated for it on the shared load balancer. `null` when public DNS is off. |\n| `connection_host` / `connection_port` | Whichever applies | The pair you should connect to right now: public when public DNS is enabled, private otherwise. |\n| `port` | Private | The **engine** port (6379, 5432, 3306). Unchanged by public DNS — kept for backwards compatibility. |\n| `endpoint` | Whichever applies | `connection_host:connection_port`, as a single string. |\n\n**Always use `connection_host` with `connection_port`.** They are resolved\ntogether, so they can never disagree. DNS records cannot encode a port, so\nresolving a public hostname tells you nothing about which port to use — and the\nengine port on the public load balancer belongs to a different instance.\n\n`port` keeps its original meaning and is unaffected by enabling public DNS, so\nexisting automation that reads it for private-network connections is unchanged.\n\nAll of these fields are additive: nothing that existed before was renamed,\nremoved, or given a new meaning, so existing integrations keep working unchanged.\n\nCredentials, including the ready-made `connection_info` URL, come from:\n\n- `GET /api/v1/database/{id}/credentials`\n- `GET /api/v1/cache/{id}/connection-info` (canonical)\n- `GET /api/v1/cache/{id}/credentials` — compatibility alias returning the\n  identical payload, with the same authorization, token permission and rate\n  limit as the canonical route\n\nEnabling public DNS (`POST /api/v1/{database,cache}/{id}/dns`) returns both\n`dns_hostname` and the allocated `dns_port`.\n\nFor databases, `username`/`password` are the **superuser** (`postgres` on\nPostgreSQL, `root` on MySQL/MariaDB) wherever the platform can resolve them, so\nthese credentials can create roles, extensions and databases. `database` is the\ndatabase that actually exists on the cluster — for a cluster created without an\nexplicit name, that is the bootstrap database, not `null`.\n\nRead endpoints (read replicas, and Redis Sentinel) are reachable on the **private\nnetwork only**. They have no public load-balancer frontend, so they keep the\nengine port even while public DNS is enabled.\n\nRotating a database or cache password is not supported through the API.\n\n## Response Format\n\nAll API responses are returned in JSON format:\n\n```json\n{\n  \"data\": [...],\n  \"pagination\": {\n    \"current_page\": 1,\n    \"last_page\": 5,\n    \"per_page\": 15,\n    \"total\": 72\n  }\n}\n```\n\n## API Token Permissions\n\nAPI tokens support granular, resource-specific permissions to control access to different parts of the API. When creating an API token, you can select which permissions to grant:\n\n### Available Scopes\n\n| Resource | Read Permission | Write Permission | Delete Permission |\n|----------|----------------|------------------|-------------------|\n| VPS Instances | `vps:read` | `vps:write` | `vps:delete` |\n| Databases | `database:read` | `database:write` | `database:delete` |\n| Cache Instances | `cache:read` | `cache:write` | `cache:delete` |\n| Object Storage | `storage:read` | `storage:write` | `storage:delete` |\n| Firewalls | `firewall:read` | `firewall:write` | `firewall:delete` |\n| Snapshots | `snapshot:read` | `snapshot:write` | `snapshot:delete` |\n| SSH Keys | `ssh-key:read` | `ssh-key:write` | `ssh-key:delete` |\n| Webhooks | `webhook:read` | `webhook:write` | - |\n| Serverless Containers | `serverless:read` | `serverless:write` | `serverless:delete` |\n| Static Sites | `static-site:read` | `static-site:write` | `static-site:delete` |\n\n### Permission Mapping\n\n- **Read**: Allows viewing/listing resources and their details\n- **Write**: Allows creating, updating, and performing actions on resources\n- **Delete**: Allows deleting resources\n\n### Default Permissions\n\nNew API tokens are created with basic read permissions by default:\n- `vps:read`\n- `database:read`\n- `cache:read`\n- `storage:read`\n- `static-site:read`\n\n### Predefined Roles\n\n- **Editor**: Read and write access to all resources\n- **Admin**: Full access including delete permissions\n\n## Rate Limiting\n\nAPI requests are rate-limited based on your account tier. Rate limit information is included in response headers:\n\n- `X-RateLimit-Limit` - Maximum requests per window\n- `X-RateLimit-Remaining` - Remaining requests\n- `X-RateLimit-Reset` - Reset timestamp\n\n## Error Handling\n\nThe API uses standard HTTP status codes:\n\n- `200 OK` - Request succeeded\n- `201 Created` - Resource created successfully\n- `204 No Content` - Success with no response body\n- `400 Bad Request` - Invalid request parameters\n- `401 Unauthorized` - Missing or invalid authentication\n- `403 Forbidden` - Insufficient permissions or token scopes\n- `404 Not Found` - Resource not found\n- `422 Unprocessable Entity` - Validation error\n- `429 Too Many Requests` - Rate limit exceeded\n- `500 Internal Server Error` - Server error\n\nError responses include details:\n\n```json\n{\n  \"message\": \"The given data was invalid.\",\n  \"errors\": {\n    \"name\": [\"The name field is required.\"]\n  }\n}\n```\n\n## SDK and Client Libraries\n\nYou can generate client SDKs in any language using our OpenAPI specification:\n\n```bash\n# Download the spec\ncurl https://danubedata.ro/docs/api.json > api-spec.json\n\n# Generate a Python client\nopenapi-generator-cli generate \\\n  -i api-spec.json \\\n  -g python \\\n  -o danubedata-python-client\n\n# Or JavaScript/TypeScript\nopenapi-generator-cli generate \\\n  -i api-spec.json \\\n  -g typescript-axios \\\n  -o danubedata-ts-client\n```\n\n## Next Steps\n\nTo access the interactive API documentation, open a new browser tab and navigate to:\n- **`/docs/api`** (or click your browser's address bar and type this path)\n\nOr explore these guides:\n- **Authentication Guide** - Learn about API tokens  \n- **Rate Limits** - Understand usage limits\n\n## Need Help?\n\n- Visit `/docs/api` in your browser for detailed examples and interactive testing\n- Contact our support team through the support portal\n- Join our community Discord for developer discussions\n\n","prev":{"title":"Rapids","slug":"cli-serverless","url":"https://docs.danubedata.ro/cli-serverless","markdown_url":"https://docs.danubedata.ro/cli-serverless.md","json_url":"https://docs.danubedata.ro/cli-serverless.json"},"next":{"title":"Authentication","slug":"api-authentication","url":"https://docs.danubedata.ro/api-authentication","markdown_url":"https://docs.danubedata.ro/api-authentication.md","json_url":"https://docs.danubedata.ro/api-authentication.json"},"index_url":"https://docs.danubedata.ro/index.json"}