Artifactory Query Language (AQL) API

openapi: 3.1.0
info:
  title: JFrog Artifactory Query Language (AQL) API
  description: >-
    Advanced search API using Artifactory Query Language (AQL), a SQL-like
    query language for finding and filtering artifacts, builds, and entries
    in JFrog Artifactory. AQL provides powerful querying capabilities
    including domain queries, field filtering, sorting, limiting, and
    inclusion of related entities.
  version: 7.x
  contact:
    name: JFrog Support
    url: https://jfrog.com/support/
    email: [email protected]
  license:
    name: Proprietary
    url: https://jfrog.com/terms-of-service/
  termsOfService: https://jfrog.com/terms-of-service/
externalDocs:
  description: Artifactory Query Language Documentation
  url: https://jfrog.com/help/r/jfrog-artifactory-documentation/artifactory-query-language
servers:
  - url: https://{server}/artifactory
    description: JFrog Artifactory Server
    variables:
      server:
        default: myserver.jfrog.io
        description: Your JFrog Platform deployment URL
security:
  - BearerAuth: []
  - ApiKeyAuth: []
  - BasicAuth: []
tags:
  - name: AQL Search
    description: Execute AQL queries to search for artifacts, builds, and entries
paths:
  /api/search/aql:
    post:
      operationId: executeAqlQuery
      summary: JFrog Artifactory Execute AQL Query
      description: >-
        Executes an Artifactory Query Language (AQL) query and returns matching
        results. AQL supports querying across multiple domains including items
        (artifacts), builds, entries, and more. Queries can include filtering,
        sorting, pagination, and inclusion of related entities.


        AQL query syntax follows the pattern:

        `domain.find(criteria).include(fields).sort(sort_criteria).offset(n).limit(n)`


        Supported primary domains:

        - **items**: Search for artifacts (files and folders)

        - **builds**: Search for build records

        - **entries**: Search for build artifact/dependency entries

        - **build.promotions**: Search for build promotions


        Example queries:

        - `items.find({"repo":"libs-release-local"})` - Find all items in a repo

        - `items.find({"name":{"$match":"*.jar"}})` - Find all JAR files

        - `items.find({"type":"file","size":{"$gt":"1000000"}}).sort({"$desc":["size"]}).limit(10)` - Top 10 largest files

        - `builds.find({"name":"my-build"}).include("module")` - Find builds with modules
      tags:
        - AQL Search
      requestBody:
        required: true
        description: >-
          AQL query string. The query uses AQL syntax, not JSON.
          Send as plain text in the request body.
        content:
          text/plain:
            schema:
              type: string
              description: AQL query string
            examples:
              findAllInRepo:
                summary: Find all items in a repository
                value: 'items.find({"repo":"libs-release-local"})'
              findByName:
                summary: Find artifacts by name pattern
                value: 'items.find({"name":{"$match":"*.jar"}})'
              findWithSort:
                summary: Find items sorted by size with limit
                value: >-
                  items.find({"type":"file"}).sort({"$desc":["size"]}).limit(10)
              findByProperty:
                summary: Find items with specific property
                value: >-
                  items.find({"@build.name":"my-build","@build.number":"123"})
              findBuilds:
                summary: Find builds by name
                value: >-
                  builds.find({"name":"my-build"}).include("module","module.artifact")
              findWithDateRange:
                summary: Find recently modified items
                value: >-
                  items.find({"modified":{"$last":"7d"},"repo":"libs-release-local"})
              findWithInclusions:
                summary: Find items including properties and stats
                value: >-
                  items.find({"repo":"libs-release-local"}).include("name","repo","path","property","stat")
              findWithPagination:
                summary: Paginated results
                value: >-
                  items.find({"repo":"libs-release-local"}).sort({"$asc":["name"]}).offset(50).limit(25)
      responses:
        '200':
          description: AQL query results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AqlResult'
        '400':
          description: Invalid AQL query syntax
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: >-
            Forbidden - non-admin users can only query within their permitted
            repositories unless the query includes repository and path criteria
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Access token authentication
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-JFrog-Art-Api
      description: API key authentication via header
    BasicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication
  schemas:
    AqlResult:
      type: object
      properties:
        results:
          type: array
          description: Array of matched results. Structure depends on the queried domain and included fields.
          items:
            $ref: '#/components/schemas/AqlResultItem'
        range:
          type: object
          description: Pagination information about the returned results
          properties:
            start_pos:
              type: integer
              description: Starting position of the results (offset)
            end_pos:
              type: integer
              description: Ending position of the results
            total:
              type: integer
              description: >-
                Total number of results matching the query (may exceed
                the returned count if limit was applied)
    AqlResultItem:
      type: object
      description: >-
        A single result item. Fields present depend on the queried domain
        and the include clause. For the items domain, common fields are shown.
      properties:
        repo:
          type: string
          description: Repository key
          example: libs-release-local
        path:
          type: string
          description: Path within the repository
          example: org/example/mylib/1.0
        name:
          type: string
          description: File or folder name
          example: mylib-1.0.jar
        type:
          type: string
          description: Item type
          enum:
            - file
            - folder
        size:
          type: integer
          description: File size in bytes
        created:
          type: string
          format: date-time
          description: Creation timestamp
        created_by:
          type: string
          description: User who created the item
        modified:
          type: string
          format: date-time
          description: Last modification timestamp
        modified_by:
          type: string
          description: User who last modified the item
        updated:
          type: string
          format: date-time
          description: Last update timestamp
        depth:
          type: integer
          description: Depth of the item in the repository tree
        actual_sha1:
          type: string
          description: SHA-1 checksum of the actual content
        actual_md5:
          type: string
          description: MD5 checksum of the actual content
        original_sha1:
          type: string
          description: SHA-1 checksum as provided during deployment
        original_md5:
          type: string
          description: MD5 checksum as provided during deployment
        sha256:
          type: string
          description: SHA-256 checksum
        virtual_repos:
          type: array
          items:
            type: string
          description: Virtual repositories that include this item
        properties:
          type: array
          description: Item properties (if included in query)
          items:
            type: object
            properties:
              key:
                type: string
                description: Property key
              value:
                type: string
                description: Property value
        stats:
          type: array
          description: Download statistics (if included in query)
          items:
            type: object
            properties:
              downloads:
                type: integer
                description: Download count
              downloaded:
                type: string
                format: date-time
                description: Last download timestamp
              downloaded_by:
                type: string
                description: User who last downloaded
              remote_downloads:
                type: integer
                description: Remote download count
              remote_downloaded:
                type: string
                format: date-time
                description: Last remote download timestamp
              remote_downloaded_by:
                type: string
                description: User who last remote downloaded
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              status:
                type: integer
                description: HTTP status code
              message:
                type: string
                description: Error message