Actian Corporation Scroll API

openapi: 3.2.0
info:
  title: Actian VectorAI DB - Search Scroll API
  description: Vector similarity search operations for Actian VectorAI DB.
  version: 1.0.0
  contact:
    name: Actian Corporation
    url: https://www.actian.com
servers:
- url: http://localhost:6573
  description: Local development server (REST API)
- url: https://api.vectorai.actian.com
  description: Production server
security:
- bearerAuth: []
tags:
- name: Scroll
  description: Pagination and iteration
paths:
  /collections/{collection_name}/points/scroll:
    post:
      tags:
      - Scroll
      summary: Scroll points
      description: Paginate through all points in a collection. The response includes a `next_page_offset` cursor that you pass as `offset` in subsequent requests to retrieve the next page. Useful for exporting data, iterating large datasets, or processing points in batches.
      operationId: scroll_points
      parameters:
      - name: collection_name
        in: path
        required: true
        schema:
          type: string
        description: The name of the collection to scroll through.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                limit:
                  type: integer
                  default: 100
                  example: 10
                  description: Maximum number of points to return per page. Must be greater than 0. For example, `20` returns 20 points per page. Defaults to 100.
                offset:
                  oneOf:
                  - type: integer
                  - type: string
                  example: 3
                  description: Cursor from a previous scroll response. Pass the `next_page_offset` value to fetch the next page. Omit or set to null for the first page.
                filter:
                  type: object
                  description: Optional filter conditions to narrow the scrolled results.
                with_payload:
                  type: boolean
                  default: true
                  example: true
                  description: Whether to include payload metadata in the response.
                with_vector:
                  type: boolean
                  default: false
                  example: false
                  description: Whether to include vector data in the response.
            examples:
              first_page:
                summary: First page
                value:
                  limit: 10
                  with_payload: true
                  with_vector: false
              next_page:
                summary: Next page
                value:
                  limit: 10
                  offset: 3
                  with_payload: true
                  with_vector: false
              with_filter:
                summary: Filtered scroll
                value:
                  limit: 10
                  filter:
                    must:
                    - key: group
                      match:
                        value: g0
                  with_payload: true
                  with_vector: false
      responses:
        '200':
          description: Scroll results
          content:
            application/json:
              schema:
                type: object
                properties:
                  usage:
                    type: object
                    properties:
                      hardware:
                        type:
                        - object
                        - 'null'
                        description: Hardware resource counters for the operation, including CPU, payload I/O, payload index I/O, and vector I/O metrics.
                  time:
                    type: number
                    format: double
                    example: 0.000129652
                    description: Time spent to process this request, in seconds.
                  status:
                    type: string
                    example: ok
                    description: Operation status.
                  result:
                    type: object
                    properties:
                      points:
                        type: array
                        description: Array of point objects in this page.
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                              example: 1
                              description: The point's unique identifier.
                            payload:
                              type:
                              - object
                              - 'null'
                              example:
                                category: A
                                value: 10
                              description: Payload metadata, or null if `with_payload` is false.
                            vector:
                              type:
                              - array
                              - 'null'
                              items:
                                type: number
                              example: null
                              description: Vector data, or null if `with_vector` is false.
                      next_page_offset:
                        oneOf:
                        - type: integer
                        - type: string
                        example: 4
                        description: Cursor for the next page. Pass this as `offset` in the next request. Null when there are no more pages.
              example:
                usage:
                  hardware: null
                time: 0.000129652
                status: ok
                result:
                  next_page_offset: 4
                  points:
                  - id: 1
                    payload:
                      category: A
                      value: 10
                    vector: null
                  - id: 2
                    payload:
                      category: B
                      value: 20
                    vector: null
                  - id: 3
                    payload:
                      category: C
                      value: 30
                    vector: null
        4XX:
          description: Error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-codeSamples:
      - lang: Python
        label: Manual scroll
        source: "from actian_vectorai_client import VectorAIClient\n\nwith VectorAIClient(\"localhost:6574\") as client:\n    # Manual cursor-based scroll\n    offset = None\n    page = 0\n    total_scrolled = 0\n    \n    while True:\n        batch, next_offset = client.points.scroll(\n            \"my_collection\",\n            limit=10,\n            offset=offset\n        )\n        page += 1\n        total_scrolled += len(batch)\n        \n        print(f\"Page {page}: {len(batch)} points\")\n        \n        if next_offset is None or len(batch) == 0:\n            break\n        offset = next_offset\n    \n    print(f\"Total scrolled: {total_scrolled}\")\n"
      - lang: Python
        label: Scroll all (convenience)
        source: "from actian_vectorai_client import VectorAIClient\n\nwith VectorAIClient(\"localhost:6574\") as client:\n    # Automatically paginate through all points\n    all_points = client.points.scroll_all(\n        \"my_collection\",\n        batch_size=15\n    )\n    print(f\"Retrieved {len(all_points)} points total\")\n"
      - lang: Python
        label: Filtered scroll
        source: "from actian_vectorai_client import VectorAIClient, Field, FilterBuilder\n\nwith VectorAIClient(\"localhost:6574\") as client:\n    # Scroll with filter\n    payload_filter = FilterBuilder().must(Field(\"group\").eq(\"g0\")).build()\n    filtered, _ = client.points.scroll(\n        \"my_collection\",\n        filter=payload_filter,\n        limit=100\n    )\n    print(f\"Found {len(filtered)} points in group g0\")\n"
      - lang: JavaScript
        label: Scroll points
        source: "import { VectorAIClient } from '@actian/vectorai-client';\n\nconst client = new VectorAIClient('localhost:6574');\n\nlet offset = undefined;\nlet page = 0;\nwhile (true) {\n    const result = await client.points.scroll('my_collection', {\n        limit: 10,\n        offset,\n        withPayload: true,\n    });\n    page++;\n    console.log(`Page ${page}: ${result.points.length} points`);\n    if (!result.nextPageOffset) break;\n    offset = result.nextPageOffset;\n}\n\nclient.close();\n"
      - lang: cURL
        label: Scroll
        source: "curl -X POST \"http://localhost:6573/collections/my_collection/points/scroll\" \\\n  -H \"Content-Type: application/json\" \\\n  -H 'Authorization: Bearer <admin-jwt-or-access-token>' \\\n  -d '{\n    \"limit\": 10,\n    \"with_payload\": true,\n    \"with_vector\": false\n  }'\n"
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        status:
          type: object
          properties:
            error:
              type: string
        time:
          type: number
          format: double
          description: Time spent to process this request, in seconds.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Admin JWT or access token for authenticating requests to VectorAI DB.