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: support@jfrog.com 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