openapi.yaml

openapi: 3.0.3
info:
  title: Tiger Cloud API
  description: |
    A RESTful API for Tiger Cloud platform.
  version: 1.0.0
  license:
    name: Proprietary
    url: https://www.tigerdata.com/legal/terms
  contact:
    name: Tiger Data Support
    url: https://www.tigerdata.com/contact
servers:
  - url: https://console.cloud.timescale.com/public/api/v1
    description: API server for Tiger Cloud

tags:
  - name: Auth
    description: Authentication and authorization information.
  - name: VPCs
    description: Manage VPCs and their peering connections.
  - name: Services
    description: Manage services, read replicas, and their associated actions.
  - name: Analytics
    description: Track analytics events.

paths:
  /auth/info:
    get:
      operationId: getAuthInfo
      tags:
        - Auth
      summary: Get Authentication Info
      description: Returns information about the authentication credentials being used to access the API
      responses:
        '200':
          description: Authentication information retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthInfo'
        '4XX':
          $ref: '#/components/responses/ClientError'

  /analytics/identify:
    post:
      operationId: identifyUser
      tags:
        - Analytics
      summary: Identify a user
      description: Identifies a user with optional properties for analytics tracking.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                properties:
                  type: object
                  additionalProperties: true
                  description: Optional map of arbitrary properties associated with the user
                  example:
                    email: "user@example.com"
                    name: "John Doe"
      responses:
        '200':
          $ref: '#/components/responses/AnalyticsResponse'
        '4XX':
          $ref: '#/components/responses/ClientError'

  /analytics/track:
    post:
      operationId: trackEvent
      tags:
        - Analytics
      summary: Track an analytics event
      description: Tracks an analytics event with optional properties.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - event
              properties:
                event:
                  type: string
                  description: The name of the event to track
                  example: service_created
                properties:
                  type: object
                  additionalProperties: true
                  description: Optional map of arbitrary properties associated with the event
                  example:
                    region: "us-east-1"
      responses:
        '200':
          $ref: '#/components/responses/AnalyticsResponse'
        '4XX':
          $ref: '#/components/responses/ClientError'

  /projects/{project_id}/vpcs:
    get:
      operationId: getVPCs
      tags:
        - VPCs
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      summary: List All VPCs
      description: Retrieves a list of all Virtual Private Clouds (VPCs).
      responses:
        '200':
          description: A list of VPCs.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/VPC'
        '4XX':
          $ref: '#/components/responses/ClientError'
    post:
      operationId: createVPC
      tags:
        - VPCs
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      summary: Create a VPC
      description: Creates a new Virtual Private Cloud (VPC).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VPCCreate'
      responses:
        '201':
          description: VPC created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VPC'
        '4XX':
          $ref: '#/components/responses/ClientError'

  /projects/{project_id}/vpcs/{vpc_id}:
    get:
      operationId: getVPC
      tags:
        - VPCs
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/VPCId'
      summary: Get a VPC
      description: Retrieves the details of a specific VPC by its ID.
      responses:
        '200':
          description: VPC details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VPC'
        '4XX':
          $ref: '#/components/responses/ClientError'
    delete:
      operationId: deleteVPC
      tags:
        - VPCs
      summary: Delete a VPC
      description: Deletes a specific VPC.
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/VPCId'
      responses:
        '204':
          description: VPC deleted successfully.
        '4XX':
          $ref: '#/components/responses/ClientError'

  /projects/{project_id}/vpcs/{vpc_id}/rename:
    post:
      operationId: renameVPC
      tags:
        - VPCs
      summary: Rename a VPC
      description: Updates the name of a specific VPC.
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/VPCId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VPCRename'
      responses:
        '200':
          description: VPC renamed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VPC'
        '4XX':
          $ref: '#/components/responses/ClientError'

  /projects/{project_id}/vpcs/{vpc_id}/peerings:
    get:
      operationId: getVPCPeerings
      tags:
        - VPCs
      summary: List VPC Peerings
      description: Retrieves a list of all VPC peering connections for a given VPC.
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/VPCId'
      responses:
        '200':
          description: A list of VPC peering connections.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Peering'
        '4XX':
          $ref: '#/components/responses/ClientError'
    post:
      operationId: createVPCPeering
      tags:
        - VPCs
      summary: Create a VPC Peering
      description: Creates a new VPC peering connection.
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/VPCId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PeeringCreate'
      responses:
        '201':
          description: VPC peering created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Peering'
        '4XX':
          $ref: '#/components/responses/ClientError'

  /projects/{project_id}/vpcs/{vpc_id}/peerings/{peering_id}:
    get:
      operationId: getVPCPeering
      tags:
        - VPCs
      summary: Get a VPC Peering
      description: Retrieves the details of a specific VPC peering connection.
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/VPCId'
        - $ref: '#/components/parameters/PeeringId'
      responses:
        '200':
          description: VPC peering details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Peering'
        '4XX':
          $ref: '#/components/responses/ClientError'
    delete:
      operationId: deleteVPCPeering
      tags:
        - VPCs
      summary: Delete a VPC Peering
      description: Deletes a specific VPC peering connection.
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/VPCId'
        - $ref: '#/components/parameters/PeeringId'
      responses:
        '204':
          description: VPC peering deleted successfully.
        '4XX':
          $ref: '#/components/responses/ClientError'

  /projects/{project_id}/services:
    get:
      operationId: getServices
      tags:
        - Services
      summary: List All Services
      description: Retrieves a list of all services within a specific project.
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      responses:
        '200':
          description: A list of services.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Service'
        '4XX':
          $ref: '#/components/responses/ClientError'
    post:
      operationId: createService
      tags:
        - Services
      summary: Create a Service
      description: Creates a new database service within a project. This is an asynchronous operation.
      parameters:
        - $ref: '#/components/parameters/ProjectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceCreate'
      responses:
        '202':
          description: Service creation request has been accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '4XX':
          $ref: '#/components/responses/ClientError'

  /projects/{project_id}/services/{service_id}:
    get:
      operationId: getService
      tags:
        - Services
      summary: Get a Service
      description: Retrieves the details of a specific service by its ID.
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/ServiceId'
      responses:
        '200':
          description: Service details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '4XX':
          $ref: '#/components/responses/ClientError'
    delete:
      operationId: deleteService
      tags:
        - Services
      summary: Delete a Service
      description: Deletes a specific service. This is an asynchronous operation.
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/ServiceId'
      responses:
        '202':
          description: Deletion request has been accepted.
        '4XX':
          $ref: '#/components/responses/ClientError'

  /projects/{project_id}/services/{service_id}/start:
    post:
      operationId: startService
      tags:
        - Services
      summary: Start a Service
      description: Starts a stopped service within a project. This is an asynchronous operation.
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/ServiceId'
      responses:
        '202':
          description: Service start request has been accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '4XX':
          $ref: '#/components/responses/ClientError'

  /projects/{project_id}/services/{service_id}/stop:
    post:
      operationId: stopService
      tags:
        - Services
      summary: Stop a Service
      description: Stops a running service within a project. This is an asynchronous operation.
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/ServiceId'
      responses:
        '202':
          description: Service stop request has been accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '4XX':
          $ref: '#/components/responses/ClientError'

  /projects/{project_id}/services/{service_id}/attachToVPC:
    post:
      operationId: attachServiceToVPC
      tags:
        - Services
      summary: Attach Service to VPC
      description: Associates a service with a VPC.
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/ServiceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceVPCInput'
      responses:
        '202':
          $ref: '#/components/responses/SuccessMessage'
        '4XX':
          $ref: '#/components/responses/ClientError'

  /projects/{project_id}/services/{service_id}/detachFromVPC:
    post:
      operationId: detachServiceFromVPC
      tags:
        - Services
      summary: Detach Service from VPC
      description: Disassociates a service from its VPC.
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/ServiceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceVPCInput'
      responses:
        '202':
          $ref: '#/components/responses/SuccessMessage'
        '4XX':
          $ref: '#/components/responses/ClientError'

  /projects/{project_id}/services/{service_id}/resize:
    post:
      operationId: resizeService
      tags:
        - Services
      summary: Resize a Service
      description: Changes the CPU and memory allocation for a specific service within a project. This is an asynchronous operation.
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/ServiceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResizeInput'
      responses:
        '202':
          description: Resize request has been accepted and is in progress.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '4XX':
          $ref: '#/components/responses/ClientError'

  /projects/{project_id}/services/{service_id}/enablePooler:
    post:
      operationId: enablePooler
      tags:
        - Services
      summary: Enable Connection Pooler for a Service
      description: Activates the connection pooler for a specific service within a project.
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/ServiceId'
      responses:
        '200':
          $ref: '#/components/responses/SuccessMessage'
        '4XX':
          $ref: '#/components/responses/ClientError'

  /projects/{project_id}/services/{service_id}/disablePooler:
    post:
      operationId: disablePooler
      tags:
        - Services
      summary: Disable Connection Pooler for a Service
      description: Deactivates the connection pooler for a specific service within a project.
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/ServiceId'
      responses:
        '200':
          $ref: '#/components/responses/SuccessMessage'
        '4XX':
          $ref: '#/components/responses/ClientError'

  /projects/{project_id}/services/{service_id}/forkService:
    post:
      operationId: forkService
      tags:
        - Services
      summary: Fork a Service
      description: Creates a new, independent service within a project by taking a snapshot of an existing one.
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/ServiceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ForkServiceCreate'
      responses:
        '202':
          description: Fork request accepted. The response contains the details of the new service being created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '4XX':
          $ref: '#/components/responses/ClientError'

  /projects/{project_id}/services/{service_id}/updatePassword:
    post:
      operationId: updatePassword
      tags:
        - Services
      summary: Update Service Password
      description: Sets a new master password for the service within a project.
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/ServiceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdatePasswordInput'
      responses:
        '204':
          description: Password updated successfully. No content returned.
        '4XX':
          $ref: '#/components/responses/ClientError'

  /projects/{project_id}/services/{service_id}/setEnvironment:
    post:
      operationId: setEnvironment
      tags:
        - Services
      summary: Set Environment for a Service
      description: Sets the environment type for the service.
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/ServiceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetEnvironmentInput'
      responses:
        '200':
          $ref: '#/components/responses/SuccessMessage'
        '4XX':
          $ref: '#/components/responses/ClientError'

  /projects/{project_id}/services/{service_id}/logs:
    get:
      operationId: getServiceLogs
      tags:
        - Services
      summary: Get service logs
      description: |
        Fetch logs for a specific service. Returns up to 500 log entries from
        available logs. Supports pagination.
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/ServiceId'
        - name: node
          in: query
          required: false
          schema:
            type: integer
          description: Specific service node to fetch logs from (for multi-node services)
        - name: page
          in: query
          required: false
          schema:
            type: integer
          description: Page number for pagination (0-based)
        - name: until
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Fetch logs before this timestamp (RFC3339 format, e.g., 2024-01-15T10:00:00Z)
      responses:
        '200':
          description: Service logs retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceLogs'
        '4XX':
          $ref: '#/components/responses/ClientError'

  /projects/{project_id}/services/{service_id}/setHA:
    post:
      operationId: setHAReplica
      tags:
        - Services
      summary: Change HA configuration for a Service
      description: Changes the HA configuration for a specific service. This is an asynchronous operation.
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/ServiceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetHAReplicaInput'
      responses:
        '202':
          description: HA replica configuration updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Service'
        '4XX':
          $ref: '#/components/responses/ClientError'

  /projects/{project_id}/services/{service_id}/replicaSets:
    get:
      operationId: getReplicaSets
      tags:
        - Read Replica Sets
      summary: Get Read Replica Sets
      description: Retrieves a list of all read replica sets associated with a primary service within a project.
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/ServiceId'
      responses:
        '200':
          description: A list of read replica sets.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ReadReplicaSet'
        '4XX':
          $ref: '#/components/responses/ClientError'
    post:
      operationId: createReplicaSet
      tags:
        - Read Replica Sets
      summary: Create a Read Replica Set
      description: Creates a new read replica set for a service. This is an asynchronous operation.
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/ServiceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReadReplicaSetCreate'
      responses:
        '202':
          description: Read replica set creation request has been accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReadReplicaSet'
        '4XX':
          $ref: '#/components/responses/ClientError'

  /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}:
    delete:
      operationId: deleteReplicaSet
      tags:
        - Read Replica Sets
      summary: Delete a Read Replica Set
      description: Deletes a specific read replica set. This is an asynchronous operation.
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/ServiceId'
        - $ref: '#/components/parameters/ReplicaSetId'
      responses:
        '202':
          description: Deletion request has been accepted.
        '4XX':
          $ref: '#/components/responses/ClientError'

  /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/resize:
    post:
      operationId: resizeReplicaSet
      tags:
        - Read Replica Sets
      summary: Resize a Read Replica Set
      description: Changes the resource allocation for a specific read replica set.
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/ServiceId'
        - $ref: '#/components/parameters/ReplicaSetId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResizeInput'
      responses:
        '202':
          description: Resize request has been accepted and is in progress.
        '4XX':
          $ref: '#/components/responses/ClientError'

  /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/enablePooler:
    post:
      operationId: enableReplicaPooler
      tags:
        - Read Replica Sets
      summary: Enable Connection Pooler for a Read Replica
      description: Activates the connection pooler for a specific read replica set.
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/ServiceId'
        - $ref: '#/components/parameters/ReplicaSetId'
      responses:
        '200':
          $ref: '#/components/responses/SuccessMessage'
        '4XX':
          $ref: '#/components/responses/ClientError'

  /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/disablePooler:
    post:
      operationId: disableReplicaPooler
      tags:
        - Read Replica Sets
      summary: Disable Connection Pooler for a Read Replica
      description: Deactivates the connection pooler for a specific read replica set.
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/ServiceId'
        - $ref: '#/components/parameters/ReplicaSetId'
      responses:
        '200':
          $ref: '#/components/responses/SuccessMessage'
        '4XX':
          $ref: '#/components/responses/ClientError'

  /projects/{project_id}/services/{service_id}/replicaSets/{replica_set_id}/setEnvironment:
    post:
      operationId: setReplicaEnvironment
      tags:
        - Read Replica Sets
      summary: Set Environment for a Read Replica
      description: Sets the environment type for the read replica set.
      parameters:
        - $ref: '#/components/parameters/ProjectId'
        - $ref: '#/components/parameters/ServiceId'
        - $ref: '#/components/parameters/ReplicaSetId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SetEnvironmentInput'
      responses:
        '200':
          $ref: '#/components/responses/SuccessMessage'
        '4XX':
          $ref: '#/components/responses/ClientError'

components:
  parameters:
    ProjectId:
      name: project_id
      in: path
      required: true
      description: The unique identifier of the project.
      schema:
        type: string
        example: "rp1pz7uyae"
    ServiceId:
      name: service_id
      in: path
      required: true
      description: The unique identifier of the service.
      schema:
        type: string
        example: "d1k5vk7hf2"
    ReplicaSetId:
      name: replica_set_id
      in: path
      required: true
      description: The unique identifier of the read replica set.
      schema:
        type: string
        example: "alb8jicdpr"
    VPCId:
      name: vpc_id
      in: path
      required: true
      description: The unique identifier of the VPC.
      schema:
        type: string
        example: "1234567890"
    PeeringId:
      name: peering_id
      in: path
      required: true
      description: The unique identifier of the VPC peering connection.
      schema:
        type: string
        example: "1234567890"

  schemas:
    AuthInfo:
      type: object
      required:
        - type
        - apiKey
      properties:
        type:
          type: string
          description: The type of authentication being used
          enum: ["apiKey"]
          example: "apiKey"
        apiKey:
          type: object
          description: Information about the API key credentials
          required:
            - public_key
            - name
            - created
            - project
            - issuing_user
          properties:
            public_key:
              type: string
              description: The public key of the client credentials
              example: "tskey_abc123"
            name:
              type: string
              description: The name of the credential
              example: "my-production-token"
            created:
              type: string
              format: date-time
              description: When the client credentials were created
              example: "2024-01-15T10:30:00Z"
            project:
              type: object
              description: Information about the project
              required:
                - id
                - name
                - plan_type
              properties:
                id:
                  type: string
                  description: The project ID
                  example: "rp1pz7uyae"
                name:
                  type: string
                  description: The name of the project
                  example: "My Production Project"
                plan_type:
                  type: string
                  description: The plan type for the project
                  example: "FREE"
            issuing_user:
              type: object
              description: Information about the user who created the credentials
              required:
                - id
                - name
                - email
              properties:
                id:
                  type: string
                  description: The user ID
                  example: "user123"
                name:
                  type: string
                  description: The user's name
                  example: "John Doe"
                email:
                  type: string
                  format: email
                  description: The user's email
                  example: "john.doe@example.com"
    VPC:
      type: object
      properties:
        id:
          type: string
          readOnly: true
          example: "1234567890"
        name:
          type: string
          example: "my-production-vpc"
        cidr:
          type: string
          example: "10.0.0.0/16"
        region_code:
          type: string
          example: "us-east-1"
    VPCCreate:
      type: object
      required:
        - name
        - cidr
        - region_code
      properties:
        name:
          type: string
          example: "my-production-vpc"
        cidr:
          type: string
          example: "10.0.0.0/16"
        region_code:
          type: string
          example: "us-east-1"
    VPCRename:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: The new name for the VPC.
          example: "my-renamed-vpc"
    Peering:
      type: object
      properties:
        id:
          type: string
          readOnly: true
          example: "1234567890"
        peer_account_id:
          type: string
          example: "acc-12345"
        peer_region_code:
          type: string
          example: "aws-us-east-1"
        peer_vpc_id:
          type: string
          example: "1234567890"
        provisioned_id:
          type: string
          example: "1234567890"
        status:
          type: string
          example: "active"
        error_message:
          type: string
          example: "VPC not found"
    PeeringCreate:
      type: object
      required:
        - peer_account_id
        - peer_region_code
        - peer_vpc_id
      properties:
        peer_account_id:
          type: string
          example: "acc-12345"
        peer_region_code:
          type: string
          example: "aws-us-east-1"
        peer_vpc_id:
          type: string
          example: "1234567890"
    Endpoint:
      type: object
      properties:
        host:
          type: string
          example: "my-service.com"
        port:
          type: integer
          example: 8080
    ConnectionPooler:
      type: object
      properties:
        endpoint:
          $ref: '#/components/schemas/Endpoint'
    Service:
      type: object
      properties:
        service_id:
          type: string
          description: The unique identifier for the service.
        project_id:
          type: string
          description: The project this service belongs to.
        name:
          type: string
          description: The name of the service.
        region_code:
          type: string
          description: The cloud region where the service is hosted.
          example: "us-east-1"
        service_type:
          $ref: '#/components/schemas/ServiceType'
          description: The type of the service.
        created:
          type: string
          format: date-time
          description: Creation timestamp
        initial_password:
          type: string
          description: The initial password for the service.
          format: password
          example: "a-very-secure-initial-password"
        status:
          $ref: '#/components/schemas/DeployStatus'
          description: Current status of the service
        resources:
          type: array
          description: List of resources allocated to the service
          items:
            type: object
            properties:
              id:
                type: string
                description: Resource identifier
              spec:
                type: object
                description: Resource specification
                properties:
                  cpu_millis:
                    type: integer
                    description: CPU allocation in millicores
                  memory_gbs:
                    type: integer
                    description: Memory allocation in gigabytes
                  volume_type:
                    type: string
                    description: Type of storage volume
        metadata:
          type: object
          description: Additional metadata for the service
          properties:
            environment:
              type: string
              description: Environment tag for the service
        endpoint:
          $ref: '#/components/schemas/Endpoint'
        vpcEndpoint:
          type: object
          nullable: true
          description: VPC endpoint configuration if available
        forked_from:
          $ref: '#/components/schemas/ForkSpec'
        ha_replicas:
          $ref: '#/components/schemas/HAReplica'
        connection_pooler:
          $ref: '#/components/schemas/ConnectionPooler'
        read_replica_sets:
          type: array
          items:
            $ref: '#/components/schemas/ReadReplicaSet'
    ServiceType:
      type: string
      enum:
      - TIMESCALEDB
      - POSTGRES
      - VECTOR
    EnvironmentTag:
        type: string
        enum:
        - DEV
        - PROD
        description: The environment tag for the service.
    ForkStrategy:
      type: string
      enum:
      - LAST_SNAPSHOT
      - NOW
      - PITR
      description: |
        Strategy for creating the fork:
        - LAST_SNAPSHOT: Use existing snapshot for fast fork
        - NOW: Create new snapshot for up-to-date fork
        - PITR: Point-in-time recovery using target_time
    DeployStatus:
      type: string
      enum:
      - QUEUED
      - DELETING
      - CONFIGURING
      - READY
      - DELETED
      - UNSTABLE
      - PAUSING
      - PAUSED
      - RESUMING
      - UPGRADING
      - OPTIMIZING
    ForkSpec:
      type: object
      properties:
        project_id:
          type: string
          example: "asda1b2c3"
        service_id:
          type: string
          example: "bbss422fg"
        is_standby:
          type: boolean
          example: false
    ReadReplicaSet:
      type: object
      properties:
        id:
          type: string
          example: "alb8jicdpr"
        name:
          type: string
          example: "reporting-replica-1"
        status:
          type: string
          enum: [creating, active, resizing, deleting, error]
          example: "active"
        nodes:
          type: integer
          description: Number of nodes in the replica set.
          example: 2
        cpu_millis:
          type: integer
          description: CPU allocation in milli-cores.
          example: 250
        memory_gbs:
          type: integer
          description: Memory allocation in gigabytes.
          example: 1
        metadata:
          type: object
          description: Additional metadata for the read replica set
          properties:
            environment:
              type: string
              description: Environment tag for the read replica set
        endpoint:
          $ref: '#/components/schemas/Endpoint'
        connection_pooler:
          $ref: '#/components/schemas/ConnectionPooler'
    ServiceCreate:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: A human-readable name for the service.
          example: "my-production-db"
        addons:
          type: array
          items:
            type: string
            enum: ["time-series", "ai"]
          description: List of addons to enable for the service. 'time-series' enables TimescaleDB, 'ai' enables AI/vector extensions.
          example: ["time-series", "ai"]
        region_code:
          type: string
          description: The region where the service will be created. If not provided, we'll choose the best region for you.
          example: "us-east-1"
        replica_count:
          type: integer
          description: Number of high-availability replicas to create (all replicas are asynchronous by default).
          example: 2
        cpu_millis:
          type: string
          description: The initial CPU allocation in milli-cores, or 'shared' for a shared-resource service.
          example: "1000"
        memory_gbs:
          type: string
          description: The initial memory allocation in gigabytes, or 'shared' for a shared-resource service.
          example: "4"
        environment_tag:
          $ref: '#/components/schemas/EnvironmentTag'
          description: The environment tag for the service, 'DEV' by default.
          default: DEV
    ForkServiceCreate:
      type: object
      required:
        - fork_strategy
      properties:
        name:
          type: string
          description: A human-readable name for the forked service. If not provided, will use parent service name with "-fork" suffix.
          example: "my-production-db-fork"
        cpu_millis:
          type: string
          description: The initial CPU allocation in milli-cores, or 'shared' for a shared-resource service. If not provided, will inherit from parent service.
          example: "1000"
        memory_gbs:
          type: string
          description: The initial memory allocation in gigabytes, or 'shared' for a shared-resource service. If not provided, will inherit from parent service.
          example: "4"
        fork_strategy:
          $ref: '#/components/schemas/ForkStrategy'
          description: Strategy for creating the fork. This field is required.
        target_time:
          type: string
          format: date-time
          description: Target time for point-in-time recovery. Required when fork_strategy is PITR.
          example: "2024-01-01T00:00:00Z"
        environment_tag:
          $ref: '#/components/schemas/EnvironmentTag'
          description: The environment tag for the forked service, 'DEV' by default.
          default: DEV
      description: |
        Create a fork of an existing service. Service type, region code, and storage are always inherited from the parent service.
        HA replica count is always set to 0 for forked services.
    HAReplica:
      type: object
      properties:
        sync_replica_count:
          type: integer
          description: Number of synchronous high-availability replicas.
          example: 1
        replica_count:
          type: integer
          description: Number of high-availability replicas (all replicas are asynchronous by default).
          example: 1
    SetHAReplicaInput:
      type: object
      properties:
        sync_replica_count:
          type: integer
          description: Number of synchronous high-availability replicas.
          example: 1
        replica_count:
          type: integer
          description: Number of high-availability replicas (all replicas are asynchronous by default).
          example: 1
      description: At least one of sync_replica_count or replica_count must be provided.
    ReadReplicaSetCreate:
      type: object
      required:
        - name
        - nodes
        - cpu_millis
        - memory_gbs
      properties:
        name:
          type: string
          description: A human-readable name for the read replica.
          example: "my-reporting-replica"
        nodes:
          type: integer
          description: Number of nodes to create in the replica set.
          example: 2
        cpu_millis:
          type: integer
          description: The initial CPU allocation in milli-cores.
          example: 250
        memory_gbs:
          type: integer
          description: The initial memory allocation in gigabytes.
          example: 1
    ResizeInput:
      type: object
      required:
        - cpu_millis
        - memory_gbs
      properties:
        cpu_millis:
          type: string
          description: The new CPU allocation in milli-cores.
          example: "1000"
        memory_gbs:
          type: string
          description: The new memory allocation in gigabytes.
          example: "4"
    UpdatePasswordInput:
      type: object
      required:
        - password
      properties:
        password:
          type: string
          description: The new password.
          format: password
          example: "a-very-secure-new-password"
    SetEnvironmentInput:
      type: object
      required:
        - environment
      properties:
        environment:
          type: string
          description: The target environment for the service.
          enum: [PROD, DEV]
      example:
        environment: "PROD"
    ServiceVPCInput:
      type: object
      required:
        - vpc_id
      properties:
        vpc_id:
          type: string
          description: The ID of the VPC to attach the service to.
          example: "1234567890"
    ServiceLogs:
      type: object
      required:
        - logs
      properties:
        logs:
          type: array
          items:
            type: string
          description: Array of log entries (up to 500 entries per page, may be empty)
    Error:
      type: object
      properties:
        code:
          type: string
        message:
          type: string

  responses:
    AnalyticsResponse:
      description: Analytics action completed successfully.
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                type: string
                description: Status of the analytics operation
                example: "success"
    SuccessMessage:
      description: The action was completed successfully.
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
                example: "Action completed successfully."
    ClientError:
      description: Client error response (4xx status codes).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'