Appwrite Advisor API

openapi: 3.0.0
info:
  title: Appwrite Advisor API
  description: Appwrite backend as a service cuts up to 70% of the time and costs required for building a modern application. We abstract and simplify common development tasks behind a REST APIs, to help you develop your app in a fast and secure way. For full API documentation and tutorials go to [https://appwrite.io/docs](https://appwrite.io/docs)
  version: 2.0.0
  termsOfService: https://appwrite.io/policy/terms
  contact:
    name: Appwrite Team
    url: https://appwrite.io/support
    email: team@appwrite.io
  license:
    name: BSD-3-Clause
    url: https://raw.githubusercontent.com/appwrite/appwrite/master/LICENSE
servers:
- url: https://cloud.appwrite.io/v1
  description: Appwrite Cloud endpoint.
- url: https://{region}.cloud.appwrite.io/v1
  description: Appwrite Cloud regional endpoint. Replace `{region}` with your project region.
  variables:
    region:
      default: fra
      description: Appwrite Cloud region.
tags:
- name: advisor
  description: The Advisor service surfaces actionable reports about your project resources, with CTA descriptors for one-click remediation in the console.
paths:
  /reports:
    get:
      summary: List reports
      operationId: advisorListReports
      tags:
      - advisor
      description: 'Get a list of all the project''s analyzer reports. You can use the query params to filter your results.

        '
      responses:
        '200':
          description: Reports List
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/reportList'
      deprecated: false
      x-appwrite:
        group: reports
        demo: advisor/list-reports.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: reports.read
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: queries
        description: 'Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: appId, type, targetType, target, analyzedAt'
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
        in: query
      - name: total
        description: When set to false, the total count returned will be 0 and will not be calculated.
        required: false
        schema:
          type: boolean
          example: false
          default: true
        in: query
  /reports/{reportId}:
    get:
      summary: Get report
      operationId: advisorGetReport
      tags:
      - advisor
      description: 'Get an analyzer report by its unique ID. The response includes the report''s metadata and the nested insights it produced.

        '
      responses:
        '200':
          description: Report
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/report'
      deprecated: false
      x-appwrite:
        group: reports
        demo: advisor/get-report.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: reports.read
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: reportId
        description: Report ID.
        required: true
        schema:
          type: string
          example: <REPORT_ID>
        in: path
    delete:
      summary: Delete report
      operationId: advisorDeleteReport
      tags:
      - advisor
      description: 'Delete an analyzer report by its unique ID. Nested insights and CTA metadata are removed asynchronously by the deletes worker.

        '
      responses:
        '204':
          description: No content
      deprecated: false
      x-appwrite:
        group: reports
        demo: advisor/delete-report.md
        rate-limit: 60
        rate-time: 60
        rate-key: projectId:{projectId},userId:{userId}
        scope: reports.write
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: reportId
        description: Report ID.
        required: true
        schema:
          type: string
          example: <REPORT_ID>
        in: path
  /reports/{reportId}/insights:
    get:
      summary: List insights
      operationId: advisorListInsights
      tags:
      - advisor
      description: 'List the insights produced under a single analyzer report. You can use the query params to filter your results further.

        '
      responses:
        '200':
          description: Insights List
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/insightList'
      deprecated: false
      x-appwrite:
        group: insights
        demo: advisor/list-insights.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: insights.read
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: reportId
        description: Parent report ID.
        required: true
        schema:
          type: string
          example: <REPORT_ID>
        in: path
      - name: queries
        description: 'Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: type, severity, status, resourceType, resourceId, parentResourceType, parentResourceId, analyzedAt, dismissedAt, dismissedBy'
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
        in: query
      - name: total
        description: When set to false, the total count returned will be 0 and will not be calculated.
        required: false
        schema:
          type: boolean
          example: false
          default: true
        in: query
  /reports/{reportId}/insights/{insightId}:
    get:
      summary: Get insight
      operationId: advisorGetInsight
      tags:
      - advisor
      description: 'Get an insight by its unique ID, scoped to its parent report.

        '
      responses:
        '200':
          description: Insight
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/insight'
      deprecated: false
      x-appwrite:
        group: insights
        demo: advisor/get-insight.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: insights.read
        platforms:
        - console
        - server
        packaging: false
        public: true
        auth:
          console:
            Project: []
          server:
            Project: []
            Key: []
      security:
      - Project: []
        Key: []
      parameters:
      - name: reportId
        description: Parent report ID.
        required: true
        schema:
          type: string
          example: <REPORT_ID>
        in: path
      - name: insightId
        description: Insight ID.
        required: true
        schema:
          type: string
          example: <INSIGHT_ID>
        in: path
components:
  schemas:
    insight:
      description: Insight
      type: object
      properties:
        $id:
          type: string
          description: Insight ID.
          example: 5e5ea5c16897e
        $createdAt:
          type: string
          description: Insight creation date in ISO 8601 format.
          example: '2020-10-15T06:38:00.000+00:00'
        $updatedAt:
          type: string
          description: Insight update date in ISO 8601 format.
          example: '2020-10-15T06:38:00.000+00:00'
        reportId:
          type: string
          description: Parent report ID. Insights always belong to a report.
          example: 5e5ea5c16897e
        type:
          type: string
          description: Insight type. One of databaseIndex (legacy), tablesDBIndex, documentsDBIndex, vectorsDBIndex, databasePerformance, sitePerformance, siteAccessibility, siteSeo, functionPerformance. The index types are engine-specific so each CTA can pair the right service+method (databases.createIndex, tablesDB.createIndex, documentsDB.createIndex, or vectorsDB.createIndex).
          example: tablesDBIndex
        severity:
          type: string
          description: Insight severity. One of info, warning, critical.
          example: warning
        status:
          type: string
          description: Insight status. One of active, dismissed.
          example: active
        resourceType:
          type: string
          description: Type of the resource the insight is about. Plural noun, e.g. databases, sites, functions.
          example: databases
        resourceId:
          type: string
          description: ID of the resource the insight is about.
          example: main
        parentResourceType:
          type: string
          description: Plural noun for the parent resource that contains the insight's resource, e.g. an insight about a column index on a table → resourceType=indexes, parentResourceType=tables. Empty when the resource has no parent.
          example: tables
        parentResourceId:
          type: string
          description: ID of the parent resource. Empty when the resource has no parent.
          example: orders
        title:
          type: string
          description: Insight title.
          example: Missing index on collection orders
        summary:
          type: string
          description: Short markdown summary describing the insight.
          example: Queries against `orders.status` are scanning the full collection.
        ctas:
          type: array
          description: List of call-to-action buttons attached to this insight.
          items:
            $ref: '#/components/schemas/insightCTA'
          example: []
        analyzedAt:
          type: string
          description: Time the insight was analyzed in ISO 8601 format.
          example: '2020-10-15T06:38:00.000+00:00'
          nullable: true
        dismissedAt:
          type: string
          description: Time the insight was dismissed in ISO 8601 format. Empty when not dismissed.
          example: '2020-10-15T06:38:00.000+00:00'
          nullable: true
        dismissedBy:
          type: string
          description: User ID that dismissed the insight. Empty when not dismissed.
          example: 5e5ea5c16897e
          nullable: true
      required:
      - $id
      - $createdAt
      - $updatedAt
      - reportId
      - type
      - severity
      - status
      - resourceType
      - resourceId
      - parentResourceType
      - parentResourceId
      - title
      - summary
      - ctas
      example:
        $id: 5e5ea5c16897e
        $createdAt: '2020-10-15T06:38:00.000+00:00'
        $updatedAt: '2020-10-15T06:38:00.000+00:00'
        reportId: 5e5ea5c16897e
        type: tablesDBIndex
        severity: warning
        status: active
        resourceType: databases
        resourceId: main
        parentResourceType: tables
        parentResourceId: orders
        title: Missing index on collection orders
        summary: Queries against `orders.status` are scanning the full collection.
        ctas: []
        analyzedAt: '2020-10-15T06:38:00.000+00:00'
        dismissedAt: '2020-10-15T06:38:00.000+00:00'
        dismissedBy: 5e5ea5c16897e
    insightCTA:
      description: InsightCTA
      type: object
      properties:
        label:
          type: string
          description: Human-readable label for the CTA, used in UI.
          example: Create missing index
        service:
          type: string
          description: 'Public API service (SDK namespace) the client should invoke. Must match the engine that owns the resource — for index suggestions: databases (legacy), tablesDB, documentsDB, or vectorsDB.'
          example: tablesDB
        method:
          type: string
          description: Public API method on the chosen service the client should invoke when this CTA is triggered.
          example: createIndex
        params:
          type: object
          additionalProperties: true
          description: Parameter map the client should pass to the service method when this CTA is triggered. Keys match the target API's parameter names (e.g. databaseId/tableId/columns for tablesDB, databaseId/collectionId/attributes for the legacy Databases API).
          example:
            databaseId: main
            tableId: orders
            key: _idx_status
            type: key
            columns:
            - status
      required:
      - label
      - service
      - method
      - params
      example:
        label: Create missing index
        service: tablesDB
        method: createIndex
        params:
          databaseId: main
          tableId: orders
          key: _idx_status
          type: key
          columns:
          - status
    insightList:
      description: Insights List
      type: object
      properties:
        total:
          type: integer
          description: Total number of insights that matched your query.
          format: int32
          example: 5
        insights:
          type: array
          description: List of insights.
          items:
            $ref: '#/components/schemas/insight'
          example: []
      required:
      - total
      - insights
      example:
        total: 5
        insights: ''
    report:
      description: Report
      type: object
      properties:
        $id:
          type: string
          description: Report ID.
          example: 5e5ea5c16897e
        $createdAt:
          type: string
          description: Report creation date in ISO 8601 format.
          example: '2020-10-15T06:38:00.000+00:00'
        $updatedAt:
          type: string
          description: Report update date in ISO 8601 format.
          example: '2020-10-15T06:38:00.000+00:00'
        appId:
          type: string
          description: ID of the third-party app that submitted the report.
          example: 5e5ea5c16897e
        type:
          type: string
          description: Analyzer that produced this report. e.g. lighthouse, audit, databaseAnalyzer.
          example: lighthouse
        title:
          type: string
          description: Short, human-readable title for the report.
          example: Lighthouse audit for https://appwrite.io/
        summary:
          type: string
          description: Markdown summary describing the report.
          example: Performance score 78. 4 opportunities found.
        targetType:
          type: string
          description: Plural noun describing what the report analyzes, e.g. databases, sites, urls.
          example: urls
        target:
          type: string
          description: Free-form target identifier (URL for lighthouse, resource ID for db).
          example: https://appwrite.io/
        categories:
          type: array
          description: Categories covered by the report, e.g. performance, accessibility.
          items:
            type: string
          example:
          - performance
          - accessibility
        insights:
          type: array
          description: Insights nested under this report.
          items:
            $ref: '#/components/schemas/insight'
          example: []
        analyzedAt:
          type: string
          description: Time the report was analyzed in ISO 8601 format.
          example: '2020-10-15T06:38:00.000+00:00'
          nullable: true
      required:
      - $id
      - $createdAt
      - $updatedAt
      - appId
      - type
      - title
      - summary
      - targetType
      - target
      - categories
      - insights
      example:
        $id: 5e5ea5c16897e
        $createdAt: '2020-10-15T06:38:00.000+00:00'
        $updatedAt: '2020-10-15T06:38:00.000+00:00'
        appId: 5e5ea5c16897e
        type: lighthouse
        title: Lighthouse audit for https://appwrite.io/
        summary: Performance score 78. 4 opportunities found.
        targetType: urls
        target: https://appwrite.io/
        categories:
        - performance
        - accessibility
        insights: []
        analyzedAt: '2020-10-15T06:38:00.000+00:00'
    reportList:
      description: Reports List
      type: object
      properties:
        total:
          type: integer
          description: Total number of reports that matched your query.
          format: int32
          example: 5
        reports:
          type: array
          description: List of reports.
          items:
            $ref: '#/components/schemas/report'
          example: []
      required:
      - total
      - reports
      example:
        total: 5
        reports: ''
  securitySchemes:
    Key:
      type: apiKey
      name: X-Appwrite-Key
      description: Your secret API key
      in: header
      x-appwrite:
        platforms:
        - server
        - console
        - manager
        demo: <YOUR_API_KEY>
    Project:
      type: apiKey
      name: X-Appwrite-Project
      description: Your project ID
      in: header
      x-appwrite:
        platforms:
        - client
        - server
        - console
        demo: <YOUR_PROJECT_ID>
externalDocs:
  description: Full API docs, specs and tutorials
  url: https://appwrite.io/docs