> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kosli.com/llms.txt
> Use this file to discover all available pages before exploring further.
## Submitting Feedback
If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:
POST https://docs.kosli.com/feedback
```json
{
"path": "/api-reference/attestation/list-attestations-for-criteria",
"feedback": "Description of the issue"
}
```
Only submit feedback when you have something specific and actionable to report.
# List attestations for criteria
> List attestations matching a search criteria within an organization.
This endpoint returns a dictionary mapping commit SHAs to lists of attestations.
Each attestation contains metadata about compliance, timing, and type-specific data.
`commit_list` is required; it scopes the search to a specific set of commits.
`attestation_type`, `attestation_name`, and `flow_name` further narrow results
within that commit set but cannot be used on their own.
## Usage Examples
### Get all attestations for a list of commits
```
GET /attestations/my-org/list_attestations_for_criteria?commit_list=ae08fc6a5c963ae8dfaa0c27d8e5de9980d433b6
```
### Narrow by flow and attestation type
```
GET /attestations/my-org/list_attestations_for_criteria?commit_list=ae08fc6a5c963ae8dfaa0c27d8e5de9980d433b6&flow_name=production-flow&attestation_type=snyk
```
### Narrow by attestation name
```
GET /attestations/my-org/list_attestations_for_criteria?commit_list=ae08fc6a5c963ae8dfaa0c27d8e5de9980d433b6&attestation_name=manual-test
```
### Narrow by custom attestation type
```
GET /attestations/my-org/list_attestations_for_criteria?commit_list=ae08fc6a5c963ae8dfaa0c27d8e5de9980d433b6&attestation_type=custom:security-scan
```
## OpenAPI
````yaml https://app.kosli.com/api/v2/openapi.json get /attestations/{org}/list_attestations_for_criteria
openapi: 3.1.0
info:
title: Kosli API
summary: The API for communicating with Kosli
description: >
# Authentication
When making requests against Kosli API, you can authenticate your requests
using a bearer token.
Set the bearer token in the request Authorization header to a valid API
key.
API Keys can be personal or for service accounts. Check the [service
accounts
documentation](https://docs.kosli.com/getting_started/service-accounts/) for
details.
## Curl example
```shell
curl -H "Authorization: Bearer <>"
https://app.kosli.com/api/v2/environments/<>
```
version: '2.0'
servers:
- url: https://app.kosli.com/api/v2
description: EU
- url: https://app.us.kosli.com/api/v2
description: US
security:
- HTTPBearer: []
paths:
/attestations/{org}/list_attestations_for_criteria:
get:
tags:
- Attestation
summary: List attestations for criteria
description: >-
List attestations matching a search criteria within an organization.
This endpoint returns a dictionary mapping commit SHAs to lists of
attestations.
Each attestation contains metadata about compliance, timing, and
type-specific data.
`commit_list` is required; it scopes the search to a specific set of
commits.
`attestation_type`, `attestation_name`, and `flow_name` further narrow
results
within that commit set but cannot be used on their own.
## Usage Examples
### Get all attestations for a list of commits
```
GET
/attestations/my-org/list_attestations_for_criteria?commit_list=ae08fc6a5c963ae8dfaa0c27d8e5de9980d433b6
```
### Narrow by flow and attestation type
```
GET
/attestations/my-org/list_attestations_for_criteria?commit_list=ae08fc6a5c963ae8dfaa0c27d8e5de9980d433b6&flow_name=production-flow&attestation_type=snyk
```
### Narrow by attestation name
```
GET
/attestations/my-org/list_attestations_for_criteria?commit_list=ae08fc6a5c963ae8dfaa0c27d8e5de9980d433b6&attestation_name=manual-test
```
### Narrow by custom attestation type
```
GET
/attestations/my-org/list_attestations_for_criteria?commit_list=ae08fc6a5c963ae8dfaa0c27d8e5de9980d433b6&attestation_type=custom:security-scan
```
operationId: >-
list_attestations_for_criteria_attestations__org__list_attestations_for_criteria_get
parameters:
- name: org
in: path
required: true
schema:
type: string
title: Org
- name: flow_name
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: The flow name to search for attestations in
title: Flow Name
description: The flow name to search for attestations in
- name: commit_list
in: query
required: false
schema:
anyOf:
- type: array
items:
type: string
pattern: ^[a-f0-9]{40}$
- type: 'null'
description: The commit list that the attestations are associated with
title: Commit List
description: The commit list that the attestations are associated with
- name: attestation_name
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: The attestation name to search for
title: Attestation Name
description: The attestation name to search for
- name: attestation_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: >-
The attestation ID to search for. Not yet supported on this
endpoint — currently ignored.
title: Attestation Id
description: >-
The attestation ID to search for. Not yet supported on this endpoint
— currently ignored.
- name: attestation_type
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: >-
The attestation type to search for. Use built-in types (e.g.,
'junit') or 'custom:' for custom types.
title: Attestation Type
description: >-
The attestation type to search for. Use built-in types (e.g.,
'junit') or 'custom:' for custom types.
responses:
'200':
description: Successfully retrieved attestations
content:
application/json:
schema:
$ref: '#/components/schemas/AttestationsListForCommitsResponse'
'400':
description: Missing required commit_list parameter
content:
application/json:
schema:
type: object
properties:
description:
type: string
default: ''
title: Description
additionalProperties: false
title: >-
Response 400 List Attestations For Criteria Attestations Org
List Attestations For Criteria Get
security:
- HTTPBearer: []
- HTTPBasic: []
components:
schemas:
AttestationsListForCommitsResponse:
patternProperties:
^[a-f0-9]{40}$:
items:
additionalProperties: true
type: object
type: array
type: object
title: AttestationsListForCommitsResponse
description: >-
Response model for listing attestations by commit.
This model represents a dictionary mapping commit SHAs to lists of
attestations.
Each attestation can be of different types (generic, junit, snyk,
pull_request, jira, sonar, custom).
examples:
- ae08fc6a5c963ae8dfaa0c27d8e5de9980d433b6:
- annotations:
key: value
artifact_fingerprint: 089eeef9ef2ba07f142d93bb172eab3f23586b4cb40af75175ce140ab9a88c9a
attestation_id: '1234567890'
attestation_name: manual-test
attestation_type: generic
created_at: 1750923680
description: this is a glorious attestation
evidence_archive_fingerprint: 960421eb617fc0ff3183cdc406f4bbc6340f10bc12ac2a83cb9a203dc3be3fc1
evidence_archive_path: /path/to/evidence.tar.gz
external_urls:
github: https://github.com/org/repo/actions/123
git_commit_info:
author: Jon Smith
branch: main
message: adding glorious commit
sha1: ae08fc6a5c963ae8dfaa0c27d8e5de9980d433b6
timestamp: 1750923680
url: >-
https://github.com/org/repo/commit/ae08fc6a5c963ae8dfaa0c27d8e5de9980d433b6
has_audit_package: true
html_url: https://app.kosli.com/org/flow/trail/attestation
is_compliant: true
origin_url: https://github.com/actions/123
reported_by: Jon Smith
target_artifacts:
- backend
user_data:
test_result: passed
securitySchemes:
HTTPBearer:
type: http
scheme: bearer
````