Cloudzy Developer API - Complete Reference & Implementation Guide

This document provides a comprehensive reference of all endpoints available in the Cloudzy Developer API v1, their implementation status in the codebase, and detailed technical specifications for implementing missing features.

🎯 Request for Changes - Implementation Tasks

This section outlines the specific changes and features that need to be implemented in the codebase. Use the technical reference sections below to understand the API specifications and implement these features following the existing codebase patterns.

Priority 1: Critical Missing Features

1. Change OS Web UI Implementation

Current Status: ⚠️ CLI Only
Location: src/main.rs (CLI implementation exists)
Task:

• Add a "Change OS" button/action to the instance detail page (templates/instance_detail.html)
• Create handler in src/handlers/instances.rs for instance_change_os_post
• Add route in src/main.rs for POST /instance/{instance_id}/change-os
• Create a form/template similar to change_pass_instance.html that allows selecting an OS from the list
• Use the existing load_os_list API function to populate OS options
• Follow the pattern used in instance_change_pass_post handler

API Endpoint: POST /v1/instances/{instanceId}/change-os
Request Schema: See "Change OS Request Schema" in Technical Reference

2. Snapshot Management

Current Status: ❌ Not Implemented
Task:

• Create new module src/api/snapshots.rs with functions:
  • load_snapshots(client, api_base_url, api_token, instance_id, filters)
  • create_snapshot(client, api_base_url, api_token, instance_id)
  • delete_snapshot(client, api_base_url, api_token, snapshot_id)
  • restore_snapshot(client, api_base_url, api_token, snapshot_id)
• Create handlers in src/handlers/snapshots.rs:
  • snapshots_list_get - List snapshots (with instance filter)
  • snapshot_create_post - Create snapshot
  • snapshot_detail_get - View snapshot details
  • snapshot_delete_post - Delete snapshot
  • snapshot_restore_post - Restore from snapshot
• Create templates:
  • templates/snapshots.html - List view
  • templates/snapshot_detail.html - Detail view
  • templates/create_snapshot.html - Create form
• Add routes in src/main.rs
• Add navigation link in templates/base.html (replace "coming soon" link)
• Add "Create Snapshot" button to instance detail page

API Endpoints:

• GET /v1/snapshots
• POST /v1/snapshots
• GET /v1/snapshots/{id}
• DELETE /v1/snapshots/{id}
• POST /v1/snapshots/{id}/restore

3. Applications (OCA) Support

Current Status: ❌ Not Implemented
Task:

• Create src/api/applications.rs with load_applications() function
• Integrate into instance creation wizard (src/handlers/wizard.rs)
• Add step or option in wizard to select one-click applications
• Update CreateInstanceRequestSchema to include appId when selected
• Display available applications with descriptions and OS compatibility

API Endpoint: GET /v1/applications

Priority 2: Important Features

4. Backup Profile Management

Current Status: ❌ Not Implemented
Task:

• Create src/api/backups.rs with functions for backup profile CRUD operations
• Create handlers in src/handlers/backups.rs:
  • backups_list_get - List backup profiles
  • backup_profile_get - Get profile for instance
  • backup_profile_create_post - Create profile
  • backup_profile_update_put - Update profile
  • backup_profile_delete_post - Delete profile
• Create templates for backup management UI
• Add "Backup Settings" section to instance detail page
• Replace "coming soon" link in navigation

API Endpoints:

• GET /v1/backups
• POST /v1/backups
• PUT /v1/backups
• GET /v1/backups/{instanceId}
• DELETE /v1/backups/{instanceId}

5. Floating IP Management

Current Status: ⚠️ Partial (only creation via instance)
Task:

• Create src/api/floating_ips.rs with functions:
  • load_floating_ips(client, api_base_url, api_token, filters)
  • create_floating_ips(client, api_base_url, api_token, region_id, count)
  • update_floating_ip(client, api_base_url, api_token, id, updates)
  • release_floating_ip(client, api_base_url, api_token, id)
• Create handlers in src/handlers/floating_ips.rs
• Create templates for floating IP list and management
• Replace "coming soon" link in navigation
• Add floating IP management section showing IPs associated with instances

API Endpoints:

• GET /v1/floating-ips
• POST /v1/floating-ips
• PATCH /v1/floating-ips/{id}
• POST /v1/floating-ips/{id}/release

6. Custom ISO Management

Current Status: ❌ Not Implemented
Task:

• Create src/api/iso.rs with functions for ISO CRUD operations
• Create handlers and templates for ISO management
• Allow users to upload/download ISO files
• Show ISO status (DOWNLOADING, READY, FAILED, DELETED)
• Replace "coming soon" link in navigation

API Endpoints:

• GET /v1/iso
• POST /v1/iso
• GET /v1/iso/{id}
• DELETE /v1/iso/{id}

7. SSH Key Detail View

Current Status: ⚠️ Partial (internal use only)
Task:

• Add handler ssh_key_detail_get in src/handlers/ssh_keys.rs
• Create template templates/ssh_key_detail.html
• Add route GET /ssh-keys/{id}
• Add link from SSH keys list to detail view

API Endpoint: GET /v1/ssh-keys/{id}

Priority 3: Nice-to-Have Features

8. Custom Image Management

Current Status: ❌ Not Implemented
Task:

• Similar to ISO management but for disk images
• Create src/api/images.rs and handlers
• Replace "coming soon" link in navigation

API Endpoints:

• GET /v1/images
• POST /v1/images
• GET /v1/images/{id}
• DELETE /v1/images/{id}

Implementation Guidelines

1. Follow Existing Patterns: Study existing implementations in:

   • src/api/instances.rs - API client patterns
   • src/handlers/instances.rs - Handler patterns
   • src/handlers/ssh_keys.rs - CRUD operation patterns
   • templates/instance_detail.html - UI patterns

2. Error Handling: Use api_call_wrapper from src/handlers/helpers.rs for consistent error handling and logging

3. Authentication: All API calls require API-Token header (handled by api_call_wrapper)

4. Templates: Use Askama templates following the pattern in src/templates/

5. Access Control: Use enforce_instance_access from src/services/instance_service.rs for instance-related operations

6. Flash Messages: Use flash messages for user feedback (see existing handlers for examples)

7. Pagination: For list endpoints, implement pagination similar to instances list

8. Status Handling: Handle async operations (like ISO/image downloads, snapshot creation) with status polling or webhooks if available

Testing Checklist

For each implemented feature:

• API client functions work correctly
• Handlers properly validate input
• Error cases are handled gracefully
• UI displays data correctly
• Flash messages show success/error feedback
• Access control is enforced
• Navigation links work
• Forms validate input client-side and server-side
• Pagination works for list views
• Status updates display correctly for async operations

Overview

The Cloudzy Developer API is designed to facilitate the management of cloud resources, specifically virtual private servers (VPS). This RESTful API allows developers to programmatically create, manage, and delete instances, as well as perform operations related to operating systems, products, regions, and applications.

API Version

• Version: v1
• Base URL: /developers (prefix for all endpoints)

Authentication

All endpoints require authentication via the API-Token header. The token must be obtained from the Cloudzy platform API settings.

Response Format

All API responses follow a standardized structure:

{
  "detail": "Human-readable description",
  "code": "OKAY" | "FAILED",
  "data": { /* Response data */ }
}

Error Codes

Common HTTP status codes:

• 2xx: Success
• 400: Bad Request
• 401: Not Authorized
• 404: Not Found
• 422: Validation Error
• 460: Low Balance (specific to instance creation/resize)
• 4xx: Other custom errors

Complete Endpoint List with Implementation Status

Instances

Regions

Products

Operating Systems

Applications

SSH Keys

Floating IPs

Custom ISO

Custom Image

Snapshots

Backups

Summary Statistics

Total Endpoints by Category

• Instances: 12 endpoints
• Regions: 1 endpoint
• Products: 1 endpoint
• Operating Systems: 1 endpoint
• Applications: 1 endpoint
• SSH Keys: 4 endpoints
• Floating IPs: 4 endpoints
• Custom ISO: 4 endpoints
• Custom Image: 4 endpoints
• Snapshots: 5 endpoints
• Backups: 5 endpoints

Total: 42 endpoints

HTTP Methods Distribution

• GET: 18 endpoints (read operations)
• POST: 18 endpoints (create/action operations)
• DELETE: 7 endpoints (delete operations)
• PATCH: 1 endpoint (update operations)
• PUT: 1 endpoint (update operations)

Implementation Status Summary

• ✅ Fully Implemented: 13 endpoints (29.5%)
• ⚠️ Partially Implemented: 3 endpoints (6.8%)
  • Change OS (CLI only)
  • SSH key details (internal use only)
  • Floating IP creation (via instance creation only)
• ❌ Not Implemented: 26 endpoints (61.9%)

Implementation Notes

1. Instance Creation: Fully implemented via multi-step wizard (/create/step-1 through /create/step-8). Supports both fixed plans and custom configurations, with options for floating IPs, SSH keys, IPv4/IPv6 assignment, and more.

2. Change OS: Implemented in CLI (main.rs), but not exposed in web UI. Could be added to instance detail page as a button/action.

3. SSH Key Details: The GET endpoint for individual SSH keys exists in the API but there's no dedicated web handler for viewing a single key's details. Currently used internally for data loading.

4. Applications: The /v1/applications endpoint is available but not used. This could be integrated into the instance creation wizard for one-click application deployments (OCA).

5. Floating IPs: Only creation during instance creation is supported (floatingIPCount parameter). Full management (list, update, release) is not implemented. UI shows "coming soon" page.

6. Custom ISO/Images: Not implemented. UI shows "coming soon" pages for these features. These would allow users to upload and use custom operating system images.

7. Snapshots: Not implemented. UI shows "coming soon" page. Snapshots are useful for backup and restore operations, allowing users to save instance state and restore it later.

8. Backups: Not implemented. UI shows "coming soon" page. Automated backup profiles would be valuable for production instances, allowing scheduled backups with retention policies.

Technical Reference - Schemas & Request/Response Formats

This section provides detailed technical specifications for implementing the API endpoints, including request schemas, response formats, enums, and examples.

Common Enums

InstanceClassEnum

["default", "cpu-optimized", "gpu-provided"]

BillingCycleEnum

["hourly", "monthly", "quarterly", "semi-annually", "annually"]

InstanceFeatureEnum

["nested", "ide", "metatrader4", "metatrader5", "vpn-vless", "vpn-vmess", "vpn-ss", "vpn-mtproto", "monitoring"]

PlanTypeEnum (for resize)

["FIXED", "CUSTOM"]

SnapshotStatusEnum

["ACTIVE", "IN_PROGRESS", "FAILED", "RESTORING"]

IsoStatusEnum / ImageStatusEnum

["DOWNLOADING", "READY", "FAILED", "DELETED"]

BackupProfileStatusEnum

["active", "inactive", "pending"]

ScheduleFrequencyEnum

["daily", "weekly"]

WeekdaysEnum

["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"]

Request Schemas

CreateInstanceRequestSchema

{
  "required": ["hostnames", "region"],
  "type": "object",
  "properties": {
    "hostnames": {
      "type": "array",
      "items": {"type": "string"},
      "minItems": 1,
      "maxItems": 10
    },
    "region": {"type": "string"},
    "productId": {"type": "string"},
    "customerId": {"type": "string"},
    "appId": {"type": "string"},
    "assignIpv4": {"type": "boolean", "default": false},
    "assignIpv6": {"type": "boolean", "default": false},
    "isDdosProtected": {"type": "boolean"},
    "billingCycle": {"$ref": "#/BillingCycleEnum", "default": "hourly"},
    "isSubscriptionAutoRenewEnabled": {"type": "boolean", "default": true},
    "isoId": {"type": "string"},
    "osId": {"type": "string"},
    "osName": {"type": "string"},
    "sshKeyIds": {
      "type": "array",
      "items": {"type": "integer"}
    },
    "featureIds": {
      "type": "array",
      "items": {"$ref": "#/InstanceFeatureEnum"}
    },
    "floatingIPCount": {
      "type": "integer",
      "minimum": 0,
      "maximum": 5,
      "default": 0
    },
    "extraResource": {"$ref": "#/ExtraResourceDetailSchema"},
    "class": {"$ref": "#/InstanceClassEnum", "default": "default"},
    "fromSnapshot": {"type": "string"}
  }
}

ExtraResourceDetailSchema

{
  "type": "object",
  "properties": {
    "cpu": {"type": "integer"},
    "ramInGB": {"type": "integer"},
    "diskInGB": {"type": "integer"},
    "bandwidthInTB": {"type": "integer"}
  }
}

ResizeInstanceRequestSchema

{
  "required": ["instanceId", "type"],
  "type": "object",
  "properties": {
    "instanceId": {"type": "string"},
    "type": {"$ref": "#/PlanTypeEnum"},
    "productId": {"type": "string"},
    "regionId": {"type": "string"},
    "extraResource": {"$ref": "#/ExtraResourceDetailSchema"}
  }
}

Change OS Request Schema

{
  "required": ["osId"],
  "type": "object",
  "properties": {
    "osId": {"type": "string"}
  }
}

SSHKeyWriteSchema

{
  "required": ["name", "publicKey"],
  "type": "object",
  "properties": {
    "name": {"type": "string"},
    "publicKey": {"type": "string"},
    "customerId": {"type": "string"}
  }
}

AddFloatingIPRequestSchema

{
  "required": ["regionId", "count"],
  "type": "object",
  "properties": {
    "regionId": {"type": "string"},
    "count": {"type": "integer"}
  }
}

UpdateFloatingIPRequestSchema

{
  "type": "object",
  "properties": {
    "autoRenew": {"type": "boolean"},
    "customerNote": {"type": "string"}
  }
}

DownloadIsoRequestSchema

{
  "required": ["name", "url", "regionId"],
  "type": "object",
  "properties": {
    "name": {"type": "string"},
    "url": {"type": "string"},
    "useVirtio": {"type": "boolean", "default": true},
    "regionId": {"type": "string"}
  }
}

DownloadImageRequestSchema

{
  "required": ["name", "url", "regionId"],
  "type": "object",
  "properties": {
    "name": {"type": "string"},
    "url": {"type": "string"},
    "format": {"type": "string"},
    "decompress": {"type": "string"},
    "regionId": {"type": "string"}
  }
}

TakeSnapshotRequestSchema

{
  "required": ["instanceId"],
  "type": "object",
  "properties": {
    "instanceId": {"type": "string"}
  }
}

CreateBackupProfileRequestSchema

{
  "required": ["instanceId", "scheduleFrequency", "periodId"],
  "type": "object",
  "properties": {
    "instanceId": {"type": "string"},
    "scheduleFrequency": {"type": "string"},
    "scheduleWeekDays": {
      "type": "array",
      "items": {"$ref": "#/WeekdaysEnum"}
    },
    "periodId": {"type": "integer"}
  }
}

UpdateBackupProfileRequestSchema

{
  "required": ["instanceId", "scheduleFrequency", "periodId"],
  "type": "object",
  "properties": {
    "instanceId": {"type": "string"},
    "scheduleFrequency": {"type": "string"},
    "scheduleWeekDays": {
      "type": "array",
      "items": {"$ref": "#/WeekdaysEnum"}
    },
    "periodId": {"type": "integer"}
  }
}

Response Schemas

Standard Response Format

All endpoints return responses in this format:

{
  "detail": "string",
  "code": "OKAY" | "FAILED",
  "data": {} | [] | null
}

InstanceDetailSchema (from GET /v1/instances/{instanceId})

{
  "required": ["id", "hostname", "vcpuCount", "ram", "disk", "class"],
  "type": "object",
  "properties": {
    "id": {"type": "string"},
    "hostname": {"type": "string"},
    "vcpuCount": {"type": "integer"},
    "ram": {"type": "integer"},
    "disk": {"type": "integer"},
    "insertedAt": {"type": "string"},
    "osId": {"type": "string"},
    "isoId": {"type": "string"},
    "fromImage": {"type": "string"},
    "os": {"$ref": "#/OsSchema"},
    "region": {"type": "string"},
    "userId": {"type": "string"},
    "appId": {"type": "string"},
    "status": {"type": "string"},
    "mainIp": {"type": "string"},
    "mainIpv6": {"type": "string"},
    "productId": {"type": "string"},
    "networkStatus": {"type": "string"},
    "discountPercent": {"type": "integer"},
    "attachIso": {"type": "boolean"},
    "extraResource": {"$ref": "#/ExtraResourceDetailSchema"},
    "class": {"$ref": "#/InstanceClassEnum"},
    "ocaData": {},
    "isDdosProtected": {"type": "boolean"},
    "customerNote": {"type": "string"},
    "adminNote": {"type": "string"},
    "features": {
      "type": "array",
      "items": {"type": "string"}
    }
  }
}

SSHKeyReadSchema

{
  "required": ["name", "publicKey", "customerId", "id"],
  "type": "object",
  "properties": {
    "id": {"type": "integer"},
    "name": {"type": "string"},
    "publicKey": {"type": "string"},
    "customerId": {"type": "string", "format": "uuid4"}
  }
}

SnapshotDetailSchema

{
  "required": ["id", "name", "status", "isInstanceDeleted", "instanceId", "userId"],
  "type": "object",
  "properties": {
    "id": {"type": "string"},
    "name": {"type": "string"},
    "size": {"type": "integer"},
    "status": {"$ref": "#/SnapshotStatusEnum"},
    "lastRestoredAt": {"type": "integer"},
    "createdAt": {"type": "integer"},
    "isInstanceDeleted": {"type": "boolean"},
    "productId": {"type": "string"},
    "instanceId": {"type": "string"},
    "userId": {"type": "string"},
    "regionId": {"type": "string"},
    "metadata": {"$ref": "#/SnapshotMetadataSchema"}
  }
}

BackupProfileSchema

{
  "required": ["instanceId", "status", "backupFiles"],
  "type": "object",
  "properties": {
    "instanceId": {"type": "string"},
    "instanceData": {"$ref": "#/SnapshotMetadataSchema"},
    "status": {"type": "string"},
    "monthlyPrice": {"type": "number"},
    "feePercentage": {"type": "integer"},
    "scheduleFrequency": {"$ref": "#/ScheduleFrequencyEnum"},
    "scheduleWeekDays": {
      "type": "array",
      "items": {"$ref": "#/WeekdaysEnum"}
    },
    "maxFiles": {"type": "integer"},
    "periodId": {"type": "integer"},
    "lastSuccessfulBackupTime": {"type": "integer"},
    "backupFiles": {
      "type": "array",
      "items": {"$ref": "#/SnapshotDetailSchema"}
    },
    "createdAt": {"type": "integer"}
  }
}

Request Examples

Create Instance (Fixed Plan)

POST /developers/v1/instances
Headers: API-Token: <token>
Content-Type: application/json

{
  "hostnames": ["my-vps-1"],
  "productId": "fixed-plan-123",
  "region": "region-456",
  "class": "default",
  "extraResource": {
    "diskInGB": 50,
    "bandwidthInTB": 2
  },
  "assignIpv4": true,
  "osId": "ubuntu-22.04",
  "sshKeyIds": [101, 102],
  "floatingIPCount": 1
}

Create Instance (Custom Config)

POST /developers/v1/instances
Headers: API-Token: <token>
Content-Type: application/json

{
  "hostnames": ["custom-instance"],
  "region": "region-456",
  "class": "cpu-optimized",
  "extraResource": {
    "cpu": 4,
    "ramInGB": 8,
    "diskInGB": 100,
    "bandwidthInTB": 5
  },
  "osId": "ubuntu-22.04",
  "assignIpv4": true
}

Resize Instance (Fixed Plan)

POST /developers/v1/instances/{instanceId}/resize
Headers: API-Token: <token>
Content-Type: application/json

{
  "type": "FIXED",
  "productId": "fixed-plan-123",
  "extraResource": {
    "diskInGB": 50,
    "bandwidthInTB": 2
  }
}

Resize Instance (Custom)

POST /developers/v1/instances/{instanceId}/resize
Headers: API-Token: <token>
Content-Type: application/json

{
  "type": "CUSTOM",
  "regionId": "region-456",
  "extraResource": {
    "cpu": 8,
    "ramInGB": 16,
    "diskInGB": 200,
    "bandwidthInTB": 10
  }
}

Change OS

POST /developers/v1/instances/{instanceId}/change-os
Headers: API-Token: <token>
Content-Type: application/json

{
  "osId": "ubuntu-22.04"
}

Create SSH Key

POST /developers/v1/ssh-keys
Headers: API-Token: <token>
Content-Type: application/json

{
  "name": "My SSH Key",
  "publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAB..."
}

Add Floating IP

POST /developers/v1/floating-ips
Headers: API-Token: <token>
Content-Type: application/json

{
  "regionId": "region-456",
  "count": 2
}

Update Floating IP

PATCH /developers/v1/floating-ips/{id}
Headers: API-Token: <token>
Content-Type: application/json

{
  "autoRenew": true,
  "customerNote": "Production server IP"
}

Download ISO

POST /developers/v1/iso
Headers: API-Token: <token>
Content-Type: application/json

{
  "name": "Custom Linux ISO",
  "url": "https://example.com/custom.iso",
  "regionId": "region-456",
  "useVirtio": true
}

Download Image

POST /developers/v1/images
Headers: API-Token: <token>
Content-Type: application/json

{
  "name": "Custom Image",
  "url": "https://example.com/image.qcow2",
  "regionId": "region-456",
  "format": "qcow2",
  "decompress": "gzip"
}

Create Snapshot

POST /developers/v1/snapshots
Headers: API-Token: <token>
Content-Type: application/json

{
  "instanceId": "instance-123"
}

Restore Snapshot

POST /developers/v1/snapshots/{id}/restore
Headers: API-Token: <token>

Create Backup Profile

POST /developers/v1/backups
Headers: API-Token: <token>
Content-Type: application/json

{
  "instanceId": "instance-123",
  "scheduleFrequency": "daily",
  "periodId": 30,
  "scheduleWeekDays": ["Monday", "Wednesday", "Friday"]
}

Update Backup Profile

PUT /developers/v1/backups
Headers: API-Token: <token>
Content-Type: application/json

{
  "instanceId": "instance-123",
  "scheduleFrequency": "weekly",
  "periodId": 7,
  "scheduleWeekDays": ["Sunday"]
}

Query Parameters

List Instances (GET /v1/instances)

• createdFrom (string, optional): UTC start time in ISO-8601 format
• createdTo (string, optional): UTC end time in ISO-8601 format
• host (string, optional): Physical server hostname
• hostName (string, optional): Filter by instance hostname
• status (string, optional): Filter by instance status
• region (string, optional): Filter by region
• isoId (string, optional): Filter by ISO ID
• osFamily (string, optional): Filter by OS family
• userId (string, optional): Filter by user ID
• ipv4 (string, optional): Filter by IPv4 address
• ipv6 (string, optional): Filter by IPv6 address
• bookmark (string, optional): Pagination bookmark
• limit (integer, optional): Page size limit (5-100, default: 10)
• includeDeleted (boolean, optional): Include deleted instances (default: false)

List Products (GET /v1/products)

• regionId (string, required): Region ID to get products for

List SSH Keys (GET /v1/ssh-keys)

• customerId (string, optional): Filter by customer ID

List Floating IPs (GET /v1/floating-ips)

• address (string, optional): Filter by IP address
• region_id (string, optional): Filter by region ID
• expires_after (number, optional): Filter by expiration
• include_deleted (boolean, optional): Include deleted IPs (default: false)
• page (integer, optional): Page number (default: 1)

List ISO (GET /v1/iso)

• status (IsoStatusEnum, optional): Filter by status
• limit (integer, optional): Page size limit
• page (integer, optional): Page number (default: 1)

List Images (GET /v1/images)

• status (ImageStatusEnum, optional): Filter by status
• limit (integer, optional): Page size limit
• page (integer, optional): Page number (default: 1)

List Snapshots (GET /v1/snapshots)

• instance_id (string, optional): Filter by instance ID
• is_automated_backup (boolean, optional): Filter automated backups (default: false)
• status (SnapshotStatusEnum, optional): Filter by status
• limit (integer, optional): Page size limit
• page (integer, optional): Page number (default: 1)

List Backup Profiles (GET /v1/backups)

• status (BackupProfileStatusEnum, optional): Filter by status

Error Response Format

Validation Error (422)

{
  "detail": [
    {
      "loc": ["body", "hostnames"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Low Balance Error (460)

{
  "detail": "You don't have enough balance for the selected product.",
  "code": "BALANCE_IS_NOT_SUFFICIENT",
  "data": {
    "minimumRequiredBalance": 203.09,
    "customerBalance": "353.00",
    "numberOfDaysBalanceValidatedAgainst": 5,
    "activeInstanceCount": 8
  }
}

Standard Error (4xx)

{
  "detail": "Error message",
  "code": "FAILED",
  "data": {
    "statusCode": 404,
    "detail": "Resource not found"
  }
}

Implementation Notes for Developers

1. Authentication: All requests must include API-Token header with a valid developer token.

2. Base URL: All endpoints are prefixed with /developers, so the full path is /developers/v1/...

3. Request Format: POST/PUT/PATCH requests should use Content-Type: application/json header.

4. Response Handling: Always check the code field in the response. "OKAY" indicates success, "FAILED" indicates an error.

5. Pagination: List endpoints use bookmark-based pagination. Check for a bookmark field in the response to get the next page.

6. Validation: The API validates all input. Invalid requests return 422 with detailed validation errors.

7. Rate Limiting: Be aware of potential rate limits. Implement retry logic with exponential backoff.

8. Idempotency: Most operations are idempotent, but always check the response to confirm the operation status.

How to Use This Document

For LLM Implementation Tasks

1. Start with "Request for Changes": Review the prioritized implementation tasks at the top of this document
2. Reference Technical Specifications: Use the "Technical Reference" section for:
   • Request/response schemas
   • Enum definitions
   • Example requests
   • Error handling patterns
3. Study Existing Code: Follow patterns from implemented features:
   • API client modules in src/api/
   • Handler modules in src/handlers/
   • Template files in templates/
4. Follow Implementation Guidelines: Adhere to the patterns and best practices outlined in the Request for Changes section

For Developers

• Use the endpoint tables to understand what's available vs implemented
• Reference schemas when building API clients or forms
• Check implementation status before starting new features
• Use examples as starting points for API calls

For Project Managers

• Review implementation status summary for progress tracking
• Use priority levels to plan sprints
• Reference testing checklist for QA planning

Summary

This document serves as a complete implementation guide for the Cloudzy Developer API integration. It provides:

1. Clear Implementation Tasks: The "Request for Changes" section outlines exactly what needs to be built, prioritized by importance
2. Complete API Reference: All 44 endpoints documented with their current implementation status
3. Technical Specifications: Detailed schemas, request/response formats, and examples for every endpoint
4. Implementation Patterns: Guidelines based on existing codebase patterns
5. Testing Checklist: Quality assurance criteria for each feature

Quick Stats

• Total Endpoints: 42
• Fully Implemented: 13 (31.0%)
• Partially Implemented: 3 (7.1%)
• Not Implemented: 26 (61.9%)

Next Steps

1. Review the "Request for Changes" section for prioritized tasks
2. Study existing implementations in src/api/ and src/handlers/
3. Use the Technical Reference section for API specifications
4. Follow the implementation guidelines and patterns
5. Complete the testing checklist for each feature

Legend

• ✅ API Available: Endpoint exists in the Developer API
• ✅ Implemented: Fully implemented in the codebase
• ⚠️ Partial: Partially implemented (CLI only, internal use, or limited functionality)
• ❌ Not Implemented: Not implemented in the codebase