repzo 1.0.291 → 1.0.293

package/src/oas/ai-object-detection-session.yaml

@@ -0,0 +1,840 @@
+openapi: 3.0.3
+info:
+  title: Repzo API - AI Object Detection Session
+  version: 1.0.0
+  description: |
+    **Object Detection Sessions** are the parent record for a single
+    AR shelf scan captured by the mobile app. A session groups N
+    `ai-object-detection-task` rows (one per submitted frame) and adds
+    aggregate 3D scene state, so the existing task-based training and
+    review pipeline is reused unchanged — a session is a thin parent,
+    the frame is still the atomic annotatable unit.
+
+    **Who calls it.** Reps create sessions implicitly when the device
+    posts its first frame to `/activity-ai-object-detection-session-frame`
+    (which upserts the session). Admins and reps list and inspect
+    sessions from the dashboard. Detection/placement is triggered later,
+    per task, via `ai-object-detection-inference`, and cross-frame fusion
+    runs through `ai-object-detection-session-analysis` (its own
+    versioned collection — see below).
+
+    **Multi-tenancy & lifecycle.** Records are scoped by
+    `company_namespace[]` (server-injected from the caller's session).
+    Soft-delete via `disabled: true`. On `DELETE`, child tasks are left
+    intact by default (they remain usable training data); pass
+    `?cascade=true` to also soft-delete the session's child tasks.
+
+    **Status FSM.** `open` (device still streaming / new frames arrived)
+    → `infer_in_progress` (an analysis run is in flight) → `inferred`
+    (last run succeeded) or `failed` (last run failed). The transitions
+    are written by `ai-object-detection-session-analysis` runs; a new
+    frame arriving on a settled (`inferred`/`failed`) session reopens it
+    to `open` (there is newer data than the last analysis). Per-run
+    status/history still lives on the analysis documents. `uploaded` is
+    written by the device's upload-complete marker (see the frame intake
+    service) — it also fires the category auto-analysis;
+    `rearbitrating` remains a reserved/legacy value with no writer.
+
+    **Key relationships.** References `clients` (the `client` /
+    store being scanned), `ai-object-detection-category` (the optional
+    `category` picked on the device — drives auto-analysis),
+    `ai.objectDetectionModelVersions` (via
+    `inference_runs.model_version`), `sv.aiObjectDetectionLabels` (via
+    `objects.label_id`), and `media.mediaStorages` (point cloud).
+    Child frames link back via the task's `session` field.
+
+    **Denormalized aggregates.** `frames_total`, `frames_accepted`,
+    `tasks_count` are incremented by the frame intake; `detections_count`
+    and `objects_count` are refreshed on every successful analysis run.
+    `scene`, `objects[]`, and `inference_runs[]` are **legacy** fields
+    from the removed in-session build_scene flow — they are retained for
+    older data but no longer written; cross-frame fused output now lives
+    in `ai-object-detection-session-analysis`.
+
+    **Population.** `?populatedKeys[]=` supports `client`, `category`,
+    `inference_runs.model_version`, `objects.label_id`, and
+    `scene.point_cloud_media`. `client`/`category` keep their ids and the
+    populated documents are returned under `client_populated` /
+    `category_populated`; the nested keys are populated in place (the
+    referenced field is replaced by the populated document).
+servers:
+  - url: https://sv.api.repzo.me
+security:
+  - ApiKeyAuth: []
+  - JwtAuth: []
+paths:
+  /ai-object-detection-session:
+    get:
+      summary: Find object detection sessions
+      operationId: findAiObjectDetectionSessions
+      parameters:
+        - in: query
+          name: _id
+          description: |
+            Filter by session `_id`. Pass once for a single match, or as
+            `?_id[]=...&_id[]=...` for multiple.
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: session_id
+          description: Filter by the device-generated session id (4-char).
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: status
+          description: Filter by lifecycle status.
+          schema:
+            oneOf:
+              - type: string
+                enum:
+                  [
+                    open,
+                    uploaded,
+                    infer_in_progress,
+                    inferred,
+                    rearbitrating,
+                    failed,
+                  ]
+              - type: array
+                items:
+                  type: string
+                  enum:
+                    [
+                      open,
+                      uploaded,
+                      infer_in_progress,
+                      inferred,
+                      rearbitrating,
+                      failed,
+                    ]
+        - in: query
+          name: client
+          description: Filter by the scanned store/client (`clients` `_id`).
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: category
+          description: Filter by the detection category (`ai-object-detection-category` `_id`).
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: rep
+          description: Filter by the rep stamped on the session's frames (`representatives` `_id`).
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: visit_id
+          description: Filter by the device visit id the scan happened in.
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: route
+          description: Filter by the visit's route (`sv.routes` `_id`).
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: creator._id
+          description: Filter by the id of the rep/admin who created the session.
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: inference_runs.model_version
+          description: Filter sessions that ran a given model version.
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: from_createdAt
+          description: Return sessions created at/after this Unix timestamp (ms).
+          schema: { type: number }
+        - in: query
+          name: to_createdAt
+          description: Return sessions created at/before this Unix timestamp (ms).
+          schema: { type: number }
+        - in: query
+          name: from_updatedAt
+          description: Cursor — sessions with `updatedAt` greater than this Unix timestamp (ms).
+          schema: { type: number }
+        - in: query
+          name: to_updatedAt
+          description: Cursor — sessions with `updatedAt` less than this Unix timestamp (ms).
+          schema: { type: number }
+        - in: query
+          name: disabled
+          description: Include disabled (soft-deleted) sessions. Defaults to `false`.
+          schema: { type: boolean, default: false }
+        - in: query
+          name: sort
+          description: Field to sort by. Defaults to `_id`.
+          schema: { type: string, default: _id }
+        - in: query
+          name: sortPageOrder
+          description: Sort direction. Defaults to descending.
+          schema: { type: string, enum: [asc, dsc], default: dsc }
+        - in: query
+          name: populatedKeys
+          description: |
+            Embed referenced documents. Supported: `client`, `category`,
+            `inference_runs.model_version`, `objects.label_id`,
+            `scene.point_cloud_media`.
+          schema:
+            type: array
+            items:
+              type: string
+              enum:
+                - client
+                - category
+                - inference_runs.model_version
+                - objects.label_id
+                - scene.point_cloud_media
+        - in: query
+          name: per_page
+          description: Page size. Defaults to the server's configured pagination limit.
+          schema: { type: integer, minimum: 1, maximum: 500 }
+          example: 50
+        - in: query
+          name: page
+          description: 1-indexed page number.
+          schema: { type: integer, minimum: 1 }
+          example: 1
+      responses:
+        "200":
+          description: Paginated list of object detection sessions.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SessionFindResult"
+    post:
+      summary: Create an object detection session
+      description: |
+        Opens a session. Usually created implicitly on the first frame
+        POST to `/activity-ai-object-detection-session-frame`; this endpoint is
+        for explicit/manual creation. `company_namespace` and `creator`
+        are server-injected.
+      operationId: createAiObjectDetectionSession
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/SessionCreateBody"
+      responses:
+        "201":
+          description: The newly-created session document.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SessionSchema"
+    patch:
+      summary: Bulk-update sessions
+      description: |
+        Bulk update via the `patch-action` writeQuery shape (e.g. bulk
+        status change or bulk disable). The rows to update are selected by
+        the SAME query filters as `GET /ai-object-detection-session`
+        (`_id`, `session_id`, `status`, `client`, `category`, `rep`,
+        `visit_id`, `route`, `creator._id`, `inference_runs.model_version`,
+        `from_/to_createdAt`, `from_/to_updatedAt`, `disabled`). Returns
+        `{ nFound, nModified }`.
+      operationId: patchAiObjectDetectionSession
+      parameters:
+        - in: query
+          name: _id
+          description: Restrict the bulk update to these session ids.
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: session_id
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: status
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: client
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: category
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: rep
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: visit_id
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: route
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: creator._id
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: inference_runs.model_version
+          schema:
+            oneOf:
+              - type: string
+              - type: array
+                items: { type: string }
+        - in: query
+          name: from_createdAt
+          schema: { type: number }
+        - in: query
+          name: to_createdAt
+          schema: { type: number }
+        - in: query
+          name: from_updatedAt
+          schema: { type: number }
+        - in: query
+          name: to_updatedAt
+          schema: { type: number }
+        - in: query
+          name: disabled
+          schema: { type: boolean }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PatchActionBody"
+      responses:
+        "200":
+          description: Bulk-update result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/PatchActionResult"
+  /ai-object-detection-session/{id}:
+    get:
+      summary: Get a session by id
+      operationId: getAiObjectDetectionSession
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: { type: string }
+        - in: query
+          name: populatedKeys
+          description: Same population keys as the list endpoint.
+          schema:
+            type: array
+            items:
+              type: string
+              enum:
+                - client
+                - category
+                - inference_runs.model_version
+                - objects.label_id
+                - scene.point_cloud_media
+      responses:
+        "200":
+          description: The session document for the given `_id`.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SessionSchema"
+    put:
+      summary: Update a session
+      description: |
+        Standard put — typically for limited fields (status corrections,
+        capture metadata). `company_namespace` is derived from the
+        caller's session.
+      operationId: updateAiObjectDetectionSession
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: { type: string }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/SessionUpdateBody"
+      responses:
+        "200":
+          description: The session document after the update is applied.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SessionSchema"
+    delete:
+      summary: Soft-delete a session
+      description: |
+        Soft-deletes the session (`disabled: true`). By default child
+        tasks are kept (usable training data). Pass `?cascade=true` to
+        also soft-delete the session's child tasks.
+      operationId: removeAiObjectDetectionSession
+      parameters:
+        - in: path
+          name: id
+          required: true
+          schema: { type: string }
+        - in: query
+          name: cascade
+          description: When `true`, also soft-delete the session's child tasks.
+          schema: { type: boolean, default: false }
+      responses:
+        "200":
+          description: "The session document after soft-deletion (`disabled: true`)."
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/SessionSchema"
+components:
+  securitySchemes:
+    ApiKeyAuth:
+      type: apiKey
+      in: header
+      name: api-key
+      description: |
+        Server-issued API key. Also accepted via the `x-api-key` header or the
+        `?apiKey=` query parameter as fallbacks.
+    JwtAuth:
+      type: apiKey
+      in: header
+      name: Authorization
+      description: |
+        Raw JWT in the `Authorization` header — **no `Bearer ` prefix**.
+        Obtained from `POST /authenticate` (admin / rep / client login).
+  schemas:
+    UserRef:
+      type: object
+      description: Compact actor reference (rep or admin).
+      properties:
+        _id: { type: string }
+        type: { type: string, enum: [admin, rep] }
+        name: { type: string }
+        rep: { type: string }
+        admin: { type: string }
+    Device:
+      type: object
+      properties:
+        platform: { type: string }
+        os: { type: string }
+        model: { type: string }
+        app_version: { type: string }
+        ar_engine: { type: string, enum: [ARKit, ARCore] }
+    CaptureSettings:
+      type: object
+      properties:
+        rate_hz: { type: number }
+        recording_enabled: { type: boolean }
+        target_distance_m: { type: number }
+        resolution:
+          type: string
+          enum: [medium, high, max]
+          description: Camera format preference active during capture.
+    Plane:
+      type: object
+      properties:
+        kind: { type: string, enum: [shelf, floor, wall] }
+        normal:
+          type: array
+          items: { type: number }
+          description: 3-float plane normal.
+        d:
+          type: number
+          description: "Plane equation constant in Ax+By+Cz+d=0."
+        inliers: { type: number }
+        bounds:
+          type: object
+          properties:
+            min: { type: array, items: { type: number } }
+            max: { type: array, items: { type: number } }
+    SessionObject:
+      type: object
+      description: Cross-frame fused object after clustering.
+      properties:
+        _id: { type: string }
+        label_id: { type: string }
+        cluster_size:
+          type: number
+          description: How many frames contributed to this object.
+        world_position:
+          type: object
+          properties:
+            x: { type: number }
+            y: { type: number }
+            z: { type: number }
+        world_orientation:
+          type: object
+          properties:
+            yaw: { type: number }
+            pitch: { type: number }
+            roll: { type: number }
+        bbox_3d:
+          type: object
+          properties:
+            min: { type: array, items: { type: number } }
+            max: { type: array, items: { type: number } }
+        placement_confidence:
+          type: number
+          description: Fused 0..1 placement confidence.
+        winning_task: { type: string }
+        winning_annotation_id: { type: string }
+        contributing_tasks:
+          type: array
+          items: { type: string }
+        arbitration:
+          type: object
+          additionalProperties: true
+          description: Weights / tiebreak rationale.
+    InferenceRun:
+      type: object
+      properties:
+        _id: { type: string }
+        model_version: { type: string }
+        started_at: { type: number }
+        finished_at: { type: number }
+        config:
+          type: object
+          additionalProperties: true
+          description: Clustering params, RANSAC config.
+        status: { type: string, enum: [pending, success, failed] }
+        triggered_by:
+          $ref: "#/components/schemas/UserRef"
+        notes: { type: string }
+    Scene:
+      type: object
+      properties:
+        planes:
+          type: array
+          items:
+            $ref: "#/components/schemas/Plane"
+        point_cloud_media:
+          type: string
+          description: "`media.mediaStorages` id of the .ply / .npy point cloud."
+        point_cloud_stats:
+          type: object
+          properties:
+            n_points: { type: number }
+            voxel_size_m: { type: number }
+            bbox_min: { type: array, items: { type: number } }
+            bbox_max: { type: array, items: { type: number } }
+        world_frame:
+          type: string
+          enum: [arkit, arcore, normalized]
+          description: Coordinate system the world positions are reported in.
+    SessionSchema:
+      type: object
+      description: Object detection session document.
+      properties:
+        _id: { type: string }
+        session_id:
+          type: string
+          description: "Device-generated session id (4-char). Election clones carry a `-E<n>` suffix."
+        source_session:
+          type: string
+          description: Provenance — the session this one was materialized from by `ai-object-detection-session-election` (absent on device-captured sessions).
+        device:
+          $ref: "#/components/schemas/Device"
+        client:
+          type: string
+          description: "`clients` `_id` of the scanned store/client (optional)."
+        client_populated:
+          type: object
+          description: Populated client document (when `client` is in `populatedKeys`).
+          additionalProperties: true
+        category:
+          type: string
+          description: |
+            `ai-object-detection-category` `_id` picked on the device before
+            calibration (optional). Drives the auto-analysis fired when the
+            device posts the upload-complete marker.
+        category_populated:
+          type: object
+          description: Populated category document (when `category` is in `populatedKeys`).
+          additionalProperties: true
+        mission:
+          type: string
+          description: |
+            `ai-object-detection-mission` `_id` the session was STARTED FROM
+            on the device ("SCAN THIS MISSION") — optional; generic scans
+            carry none. The attribution anchor: mission completions and
+            mission-result rows credit THIS mission only.
+        rep:
+          type: string
+          description: "`representatives` `_id` sent on the frames (defaults to the rep in the token) — the scanning rep for api-key intakes."
+        visit_id:
+          type: string
+          description: |
+            Device visit id (`visits.visit_id`) of the visit the scan happened
+            in — stamped by the frame intake, stored as-is (visits sync after
+            the fact, never resolved to a server ref). Copied onto the
+            mission/metric results so the assigned-missions read can tell
+            "done in THIS visit".
+        route:
+          type: string
+          description: "`sv.routes` `_id` of the visit's route, as sent by the device."
+        business_day:
+          type: string
+          description: "Business day of the scan, `YYYY-MM-DD` — as sent by the device, else stamped once from the capture time under the rep's stamping context (shift schedule, `end_of_day` cut, time zone)."
+        time_zone:
+          type: string
+          description: IANA timezone of the device at capture, as sent by the device.
+        aisle_label: { type: string }
+        aisle_length_m: { type: number }
+        capture_settings:
+          $ref: "#/components/schemas/CaptureSettings"
+        status:
+          type: string
+          enum:
+            [open, uploaded, infer_in_progress, inferred, rearbitrating, failed]
+        _errors:
+          type: array
+          items: { type: object, additionalProperties: true }
+        frames_total: { type: number }
+        frames_accepted: { type: number }
+        tasks_count: { type: number }
+        detections_count: { type: number }
+        objects_count: { type: number }
+        ground:
+          type: object
+          description: |
+            Floor lock measured on-device at capture entry (absent when the
+            rep skipped it). World Y is gravity-aligned, so the height above
+            the floor of any world point is "y - ground.y_world".
+          properties:
+            y_world:
+              { type: number, description: Floor height (world Y), metres. }
+            samples: { type: integer }
+            spread_m:
+              {
+                type: number,
+                description: Lock quality (IQR of the samples),
+                metres.,
+              }
+            camera_height_m: { type: number }
+        eye_level_m:
+          type: number
+          description: |
+            Camera height above the locked floor while shooting the shelf,
+            metres — the rep's standing eye level.
+        world_alignment:
+          type: string
+          description: "'gravity' on both ARKit/ARCore — recorded, not assumed."
+        coverage_m2:
+          type: number
+          description: Device-computed swept shelf area, m² — includes quality-rejected (never uploaded) attempts, so it cannot be recomputed server-side. Monotonic per session.
+        ground_skipped:
+          type: boolean
+          description: The rep tapped Skip on the floor point (a deliberate choice, unlike a lock that never converged).
+        session_score:
+          type: number
+          description: "Election evaluation — average frame quality, 0..1 (written by `ai-object-detection-session-election`)."
+        session_verdict:
+          type: string
+          enum: [excellent, good, acceptable, rejected]
+          description: Articulated verdict from `session_score` against the namespace detection-settings score bands; `rejected` when any rejection reason fired.
+        rejection_reasons:
+          type: array
+          items: { type: string }
+          description: "Session gates that fired at election: `coverage_below_target`, `jump_detected`, `too_many_elected`."
+        election_excluded:
+          type: array
+          description: Error-tier frames excluded from the election (they stay on the source session).
+          items:
+            type: object
+            properties:
+              task: { type: string }
+              violations:
+                type: array
+                items: { type: string }
+        scene:
+          $ref: "#/components/schemas/Scene"
+        objects:
+          type: array
+          items:
+            $ref: "#/components/schemas/SessionObject"
+        inference_runs:
+          type: array
+          items:
+            $ref: "#/components/schemas/InferenceRun"
+        creator:
+          $ref: "#/components/schemas/UserRef"
+        editor:
+          $ref: "#/components/schemas/UserRef"
+        disabled: { type: boolean }
+        company_namespace:
+          type: array
+          items: { type: string }
+          description: Tenant key. Server-injected — never accept from clients.
+        createdAt: { type: string, format: date-time }
+        updatedAt: { type: string, format: date-time }
+    SessionCreateBody:
+      type: object
+      description: |
+        Body for opening a session. `creator` and the aggregate counters are
+        server-managed. The tenant key (`company_namespace`) is optional for
+        SDK callers and is otherwise injected from the caller's session.
+      properties:
+        session_id: { type: string }
+        source_session: { type: string }
+        device:
+          $ref: "#/components/schemas/Device"
+        client: { type: string }
+        category: { type: string }
+        mission: { type: string }
+        rep: { type: string }
+        visit_id: { type: string }
+        route: { type: string }
+        business_day:
+          type: string
+          description: "`YYYY-MM-DD`."
+        time_zone: { type: string }
+        capture_settings:
+          $ref: "#/components/schemas/CaptureSettings"
+        coverage_m2: { type: number }
+        ground:
+          type: object
+          properties:
+            y_world: { type: number }
+            samples: { type: integer }
+            spread_m: { type: number }
+            camera_height_m: { type: number }
+        eye_level_m: { type: number }
+        ground_skipped: { type: boolean }
+        world_alignment: { type: string }
+        status:
+          type: string
+          enum:
+            [open, uploaded, infer_in_progress, inferred, rearbitrating, failed]
+          default: open
+        company_namespace:
+          type: array
+          items: { type: string }
+          description: Optional tenant namespace override for SDK callers.
+    SessionUpdateBody:
+      type: object
+      description: |
+        Body for updating a session (any stored field; `editor` is
+        server-stamped). The tenant key is derived from the caller's
+        session. Set `disabled: true` to soft-delete.
+      properties:
+        session_id: { type: string }
+        device:
+          $ref: "#/components/schemas/Device"
+        client: { type: string }
+        category: { type: string }
+        mission: { type: string }
+        rep: { type: string }
+        visit_id: { type: string }
+        route: { type: string }
+        business_day: { type: string }
+        time_zone: { type: string }
+        capture_settings:
+          $ref: "#/components/schemas/CaptureSettings"
+        coverage_m2: { type: number }
+        ground:
+          type: object
+          properties:
+            y_world: { type: number }
+            samples: { type: integer }
+            spread_m: { type: number }
+            camera_height_m: { type: number }
+        eye_level_m: { type: number }
+        ground_skipped: { type: boolean }
+        world_alignment: { type: string }
+        status:
+          type: string
+          enum:
+            [open, uploaded, infer_in_progress, inferred, rearbitrating, failed]
+        disabled: { type: boolean }
+    PatchActionWrite:
+      type: object
+      properties:
+        key: { type: string }
+        command:
+          type: string
+          enum: [set, addToSet, pull]
+        value: {}
+    PatchActionBody:
+      type: object
+      description: Bulk-update body. `writeQuery[]` describes the writes applied to filtered rows.
+      properties:
+        writeQuery:
+          type: array
+          items:
+            $ref: "#/components/schemas/PatchActionWrite"
+    PatchActionResult:
+      type: object
+      properties:
+        nFound: { type: number }
+        nModified: { type: number }
+    SessionFindResult:
+      type: object
+      description: Standard paginated result envelope.
+      properties:
+        data:
+          type: array
+          items:
+            $ref: "#/components/schemas/SessionSchema"
+        total_result: { type: number }
+        current_count: { type: number }
+        total_pages: { type: number }
+        current_page: { type: number }
+        per_page: { type: number }
+        first_page_url: { type: string }
+        last_page_url: { type: string }
+        next_page_url: { type: string, nullable: true }
+        prev_page_url: { type: string, nullable: true }
+        path: { type: string }