Add Vector Databases API spec for public preview

specification/DigitalOcean-public.v2.yaml

@@ -583,6 +583,13 @@ tags:
 
       To interact with Uptime, you will generally send requests to the Uptime endpoint at `/v2/uptime/`.
 
+  - name: Vector Databases
+    description: |-
+      Vector DB provides APIs for provisioning and managing vector database instances
+      on DigitalOcean. By sending requests to the `/v2/vector-databases` endpoint,
+      you can list, create, update, resize, and delete vector database instances,
+      manage tags, retrieve admin credentials, and work with backups and restores.
+
   - name: "VPC NAT Gateways"
     description: |-
       [VPC NAT Gateways](https://docs.digitalocean.com/products/networking/vpc/how-to/create-nat-gateway/)
@@ -698,6 +705,7 @@ x-tagGroups:
       - SSH Keys
       - Tags
       - Uptime
+      - Vector Databases
       - VPC NAT Gateways
       - VPC Peerings
       - VPCs
@@ -2339,6 +2347,42 @@ paths:
     delete:
       $ref: "resources/tags/tags_unassign_resources.yml"
 
+  /v2/vector-databases:
+    get:
+      $ref: "resources/vector_databases/vector_databases_list.yml"
+    post:
+      $ref: "resources/vector_databases/vector_databases_create.yml"
+
+  /v2/vector-databases/{id}:
+    get:
+      $ref: "resources/vector_databases/vector_databases_get.yml"
+    put:
+      $ref: "resources/vector_databases/vector_databases_update.yml"
+    delete:
+      $ref: "resources/vector_databases/vector_databases_delete.yml"
+
+  /v2/vector-databases/{id}/backups:
+    get:
+      $ref: "resources/vector_databases/vector_databases_list_backups.yml"
+
+  /v2/vector-databases/{id}/backups/{backup_id}/restore:
+    get:
+      $ref: "resources/vector_databases/vector_databases_get_restore_status.yml"
+    post:
+      $ref: "resources/vector_databases/vector_databases_restore_backup.yml"
+
+  /v2/vector-databases/{id}/credentials:
+    get:
+      $ref: "resources/vector_databases/vector_databases_get_credentials.yml"
+
+  /v2/vector-databases/{id}/resize:
+    post:
+      $ref: "resources/vector_databases/vector_databases_resize.yml"
+
+  /v2/vector-databases/{id}/tags:
+    put:
+      $ref: "resources/vector_databases/vector_databases_update_tags.yml"
+
   /v2/volumes:
     get:
       $ref: "resources/volumes/volumes_list.yml"

specification/resources/vector_databases/examples/curl/vector_databases_create.yml

@@ -0,0 +1,7 @@
+lang: cURL
+source: |-
+  curl -X POST \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    -d '{"name": "my-vector-db", "region": "nyc3", "size": "medium", "tags": ["production"]}' \
+    "https://api.digitalocean.com/v2/vector-databases"

specification/resources/vector_databases/examples/curl/vector_databases_delete.yml

@@ -0,0 +1,6 @@
+lang: cURL
+source: |-
+  curl -X DELETE \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v2/vector-databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30"

specification/resources/vector_databases/examples/curl/vector_databases_get.yml

@@ -0,0 +1,6 @@
+lang: cURL
+source: |-
+  curl -X GET \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v2/vector-databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30"

specification/resources/vector_databases/examples/curl/vector_databases_get_credentials.yml

@@ -0,0 +1,6 @@
+lang: cURL
+source: |-
+  curl -X GET \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v2/vector-databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/credentials"

specification/resources/vector_databases/examples/curl/vector_databases_get_restore_status.yml

@@ -0,0 +1,6 @@
+lang: cURL
+source: |-
+  curl -X GET \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v2/vector-databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/backups/vectordb-9cc10173-e9ea-4176-9dbc-a4cee4c4ff30-20240101-120000/restore"

specification/resources/vector_databases/examples/curl/vector_databases_list.yml

@@ -0,0 +1,6 @@
+lang: cURL
+source: |-
+  curl -X GET \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v2/vector-databases"

specification/resources/vector_databases/examples/curl/vector_databases_list_backups.yml

@@ -0,0 +1,6 @@
+lang: cURL
+source: |-
+  curl -X GET \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    "https://api.digitalocean.com/v2/vector-databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/backups"

specification/resources/vector_databases/examples/curl/vector_databases_resize.yml

@@ -0,0 +1,7 @@
+lang: cURL
+source: |-
+  curl -X POST \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    -d '{"size": "large"}' \
+    "https://api.digitalocean.com/v2/vector-databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/resize"

specification/resources/vector_databases/examples/curl/vector_databases_restore_backup.yml

@@ -0,0 +1,7 @@
+lang: cURL
+source: |-
+  curl -X POST \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    -d '{"id": "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "backup_id": "vectordb-9cc10173-e9ea-4176-9dbc-a4cee4c4ff30-20240101-120000"}' \
+    "https://api.digitalocean.com/v2/vector-databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/backups/vectordb-9cc10173-e9ea-4176-9dbc-a4cee4c4ff30-20240101-120000/restore"

specification/resources/vector_databases/examples/curl/vector_databases_update.yml

@@ -0,0 +1,7 @@
+lang: cURL
+source: |-
+  curl -X PUT \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    -d '{"id": "9cc10173-e9ea-4176-9dbc-a4cee4c4ff30", "config": {"default_quantization": "rq", "enable_auto_schema": true, "weaviate_version": "1.24.0"}}' \
+    "https://api.digitalocean.com/v2/vector-databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30"

specification/resources/vector_databases/examples/curl/vector_databases_update_tags.yml

@@ -0,0 +1,7 @@
+lang: cURL
+source: |-
+  curl -X PUT \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
+    -d '{"tags": ["production", "staging"]}' \
+    "https://api.digitalocean.com/v2/vector-databases/9cc10173-e9ea-4176-9dbc-a4cee4c4ff30/tags"

specification/resources/vector_databases/models/vector_database.yml

@@ -0,0 +1,77 @@
+type: object
+
+description: VectorDB represents a provisioned vector database instance.
+
+properties:
+  id:
+    type: string
+    example: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30
+    description: A unique ID that can be used to identify and reference a vector database.
+    readOnly: true
+  name:
+    type: string
+    example: my-vector-db
+    description: A unique, human-readable name referring to a vector database.
+  region:
+    type: string
+    example: nyc3
+    description: The slug identifier for the region where the vector database is located.
+  owner_uuid:
+    type: string
+    example: 8b3b4c5d-6e7f-8901-a234-567890bcdef0
+    description: The UUID of the account that owns the vector database.
+    readOnly: true
+  status:
+    type: string
+    enum:
+      - pending
+      - creating
+      - active
+      - errored
+      - deleting
+    example: active
+    description: 'Lifecycle state: pending, creating, active, errored, or deleting.'
+    readOnly: true
+  config:
+    allOf:
+      - $ref: './vector_database_config.yml'
+    description: Advanced configuration.
+  created_at:
+    type: string
+    format: date-time
+    example: '2024-01-11T18:37:36Z'
+    description: >-
+      A time value given in ISO8601 combined date and time format that represents
+      when the vector database was created.
+    readOnly: true
+  updated_at:
+    type: string
+    format: date-time
+    example: '2024-01-11T18:37:36Z'
+    description: >-
+      A time value given in ISO8601 combined date and time format that represents
+      when the vector database was last updated.
+    readOnly: true
+  endpoints:
+    allOf:
+      - $ref: './vector_database_endpoints.yml'
+    description: Connection endpoints for the database instance.
+    readOnly: true
+  size:
+    type: string
+    enum:
+      - small
+      - medium
+      - large
+    example: medium
+    description: 'Resource tier: small, medium, or large.'
+  tags:
+    type: array
+    items:
+      type: string
+    example:
+      - production
+    nullable: true
+    description: >-
+      An array of tags (as strings) to organize your vector database.
+      <br><br>Requires `tag:create` scope.

specification/resources/vector_databases/models/vector_database_backup.yml

@@ -0,0 +1,24 @@
+type: object
+
+description: Backup represents a single backup of a vector database.
+
+properties:
+  backup_id:
+    type: string
+    example: vectordb-9cc10173-e9ea-4176-9dbc-a4cee4c4ff30-20240101-120000
+    description: >-
+      Unique identifier for the backup (e.g., "vectordb-{uuid}-20240101-120000").
+  status:
+    type: string
+    example: SUCCESS
+    description: 'Status of the backup: SUCCESS.'
+  started_at:
+    type: string
+    format: date-time
+    example: '2024-01-01T12:00:00Z'
+    description: Timestamp when the backup process started.
+  completed_at:
+    type: string
+    format: date-time
+    example: '2024-01-01T12:05:00Z'
+    description: Timestamp when the backup process completed.

specification/resources/vector_databases/models/vector_database_config.yml

@@ -0,0 +1,24 @@
+type: object
+
+description: VectorDBConfig holds optional, advanced cluster settings.
+
+properties:
+  default_quantization:
+    type: string
+    enum:
+      - rq
+      - pq
+      - bq
+      - sq
+    example: rq
+    description: >-
+      Default vector compression for new collections: rq, pq, bq, or sq. Empty
+      means platform default (rq).
+  enable_auto_schema:
+    type: boolean
+    example: true
+    description: Whether to enable automatic schema creation for new collections.
+  weaviate_version:
+    type: string
+    example: '1.24.0'
+    description: The Weaviate version running on the vector database cluster.

specification/resources/vector_databases/models/vector_database_credentials.yml

@@ -0,0 +1,13 @@
+type: object
+
+properties:
+  user_id:
+    type: string
+    example: admin-user-abc123
+    description: >-
+      Weaviate DB user id from the cluster secret (opaque; matches what was
+      provisioned).
+  api_token:
+    type: string
+    example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+    description: API token for that user.

specification/resources/vector_databases/models/vector_database_endpoints.yml

@@ -0,0 +1,15 @@
+type: object
+
+description: VectorDBEndpoints contains the connection endpoints for a vector database instance.
+
+properties:
+  http:
+    type: string
+    example: https://my-db-abc123.vectordb.digitalocean.com
+    description: >-
+      HTTP endpoint (e.g. "https://my-db-abc123.vectordb.digitalocean.com").
+  grpc:
+    type: string
+    example: my-db-abc123.vectordb.digitalocean.com:443
+    description: >-
+      gRPC endpoint (e.g. "my-db-abc123.vectordb.digitalocean.com:443").

specification/resources/vector_databases/models/vector_database_restore_status.yml

@@ -0,0 +1,26 @@
+type: object
+
+properties:
+  backup_id:
+    type: string
+    example: vectordb-9cc10173-e9ea-4176-9dbc-a4cee4c4ff30-20240101-120000
+    description: The backup ID being restored.
+  status:
+    type: string
+    enum:
+      - STARTED
+      - TRANSFERRING
+      - TRANSFERRED
+      - FINALIZING
+      - SUCCESS
+      - FAILED
+      - CANCELLING
+      - CANCELED
+    example: STARTED
+    description: >-
+      Current status: STARTED, TRANSFERRING, TRANSFERRED, FINALIZING, SUCCESS,
+      FAILED, CANCELLING, CANCELED.
+  error:
+    type: string
+    example: ''
+    description: Error message if the restore failed.

specification/resources/vector_databases/parameters.yml

@@ -0,0 +1,17 @@
+id:
+  in: path
+  name: id
+  description: A unique identifier for a vector database.
+  required: true
+  example: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30
+  schema:
+    type: string
+
+backup_id:
+  in: path
+  name: backup_id
+  description: A unique identifier for a vector database backup.
+  required: true
+  example: vectordb-9cc10173-e9ea-4176-9dbc-a4cee4c4ff30-20240101-120000
+  schema:
+    type: string

specification/resources/vector_databases/responses/vector_database.yml

@@ -0,0 +1,38 @@
+description: A JSON object with a key of `vector_db`.
+
+headers:
+  ratelimit-limit:
+    $ref: '../../../shared/headers.yml#/ratelimit-limit'
+  ratelimit-remaining:
+    $ref: '../../../shared/headers.yml#/ratelimit-remaining'
+  ratelimit-reset:
+    $ref: '../../../shared/headers.yml#/ratelimit-reset'
+
+content:
+  application/json:
+    schema:
+      type: object
+      properties:
+        vector_db:
+          $ref: '../models/vector_database.yml'
+      required:
+        - vector_db
+    example:
+      vector_db:
+        id: 9cc10173-e9ea-4176-9dbc-a4cee4c4ff30
+        name: my-vector-db
+        region: nyc3
+        owner_uuid: 8b3b4c5d-6e7f-8901-a234-567890bcdef0
+        status: active
+        config:
+          default_quantization: rq
+          enable_auto_schema: true
+          weaviate_version: '1.24.0'
+        created_at: '2024-01-11T18:37:36Z'
+        updated_at: '2024-01-11T18:37:36Z'
+        endpoints:
+          http: https://my-db-abc123.vectordb.digitalocean.com
+          grpc: my-db-abc123.vectordb.digitalocean.com:443
+        size: medium
+        tags:
+          - production