Prepare Evidence

Subscription Information

This feature is supported with the Enterprise+ license.

Description: Prepares evidence in accordance with the DSSE standard that can then be attached to an artifact in Artifactory with the Deploy Evidence REST API. Use these two APIs as an alternative to using the Create Evidence CLI.Create Evidence CLI

Note

For the complete workflow, see Create Evidence using REST APIs.Create Evidence using REST APIs

Since: 7.129.1

Security: Requires a valid token; requires Read and Annotate permissions to the subject repository path

Usage: POST /evidence/api/v1/evidence/prepare

Content Type: application/json

Query Parameters (optional):

Parameter	Type	Description
`include_pae`	boolean	When set to `true`, the API returns a Pre-Authentication Encoding (PAE) statement, which is used by DSSE as a standardized format for signing the payload. The default value is `false`, which means the API does not create the PAE. In such cases, you must create the PAE manually before the payload can be signed.

Parameter

Type

Description

include_pae

boolean

When set to true, the API returns a Pre-Authentication Encoding (PAE) statement, which is used by DSSE as a standardized format for signing the payload.

The default value is false, which means the API does not create the PAE. In such cases, you must create the PAE manually before the payload can be signed.

Request Body Parameters:

Parameter	Required	Type	Description
`predicate_type`	required	string	A unique, URL-style identifier that serves as a schema or category for the evidence. The predicate type allows for programmatic querying and policy enforcement based on the evidence type.
`predicate`	required	json object	Contains the actual body of the evidence, which is comprised of arbitrary claims about the evidence subject. For more information, see Evidence Predicate.Evidence Predicate
`markdown`	optional	string	A markdown version of the predicate.
`provider_id`	optional	string	The name of the provider who owns the predicate. If provided, the platform UI will display a relevant icon for that provider alongside the evidence.
`project_key`	optional	string	The project associated with the evidence subject. For example, if the subject is an AppTrust application version, enter the `project_key` associated with that application version. This parameter is not required if the subject was created in the default project or without a project.
`subject`	required	object	The subject of the evidence being prepared. Each evidence item can have a single subject.
`subject.sha256`	optional	string	When provided, the Evidence service validates the sha256 of the subject's leading file.
`subject.subject_type`	required	string	The evidence subject type: `artifact` `build` `package` `release_bundle` `application_version`
`subject.repo_path`	required for subject type `artifact`	string	The repository key and path to the artifact (for example, generic-local/docs/readme.txt).
`subject.build_name`	required for subject type `build`	string	The build name.
`subject.build_number`	required for subject type `build`	string	The build number.
`subject.build_timestamp`	optional for subject type `build`	string	The timestamp of the build in ISO 8601 format.
`subject.release_bundle_name`	required for subject type `release_bundle`	string	The Release Bundle name.
`subject.release_bundle_version`	required for subject type `release_bundle`	string	The Release Bundle version.
`subject.package_repo`	required for subject type `package`	string	The repository containing the package.
`subject.package_name`	required for subject type `package`	string	The package name.
`subject.package_version`	required for subject type `version`	string	The package version.
`subject.application_key`	required for subject type `application_version`	string	The unique application identifier.
`subject.application_version`	required for subject type `application_version`	string	The application version.

Sample Request:

curl  -X POST -H 'Content-Type: application/json' \
 -H "Authorization: Bearer $DEMO_TOKEN" \
 --data @prepare_request.json -o prepare_response.json \
 http://localhost:8182/evidence/api/v1/evidence/prepare?include_pae=true

Sample Request Body:

For sample requests using different types of payload subjects, see Prepare Evidence - Sample Payloads.

{
  "predicate_type": "https://example.com/test/v1",
  "predicate": {
    "description": "QA manager approval",
    "approver": {
      "role": "QA manager",
      "name": "John Bill"
    }
  },
  "project_key": "catalina",
  "subject": {
    "subject_type": "artifact",
    "repo_path": "catalina-dev-generic-local/catalina-1.0.0.txt"
  }
}

Sample Response:

{
  "post_url" : "/evidence/api/v1/subject/catalina-application-versions/test-app-promotion-e2e-1764232143962/1.0.0/release-bundle.json.evd?providerId=sonar",
  "dsse_payload" : "eyJfdHlwZSI6Imh0dHBzOi8vaW4tdG90by5pby9TdGF0ZW1lbnQvdjEiLCJjcmVhdGVkQXQiOiIyMDI1LTExLTI3VDA4OjI5OjE5LjQwNFoiLCJjcmVhdGVkQnkiOiJjcmVhdGVfZHNzZV91c2VyIiwicHJlZGljYXRlIjp7InFhX3N0YXR1cyI6InBhc3NlZCIsInRlc3RlciI6InFhLXRlYW0iLCJ0ZXN0c19leGVjdXRlZCI6NDIsInRlc3RzX2ZhaWxlZCI6MCwidGVzdHNfcGFzc2VkIjo0Mn0sInByZWRpY2F0ZVR5cGUiOiJodHRwczovL3NvbmFyLmNvbS9ldmlkZW5jZS9zb25hcnF1YmUvdjEiLCJzdGFnZSI6IlFBIiwic3ViamVjdCI6W3siZGlnZXN0Ijp7InNoYTI1NiI6ImExMDhhY2U4ZDk5MWM2ZDJiMDlkZDE4ZmVhOTFlYjZhMmI3MGE2MzQxYmZmNzI2MzhiMDUxYzQzZmU0Mjg2ZTMifX1dfQ==",
  "dsse_payload_type" : "application/vnd.in-toto+json",
  "pre_authentication_encoding" : "DSSEv1 28 application/vnd.in-toto+json 394 {\"_type\":\"https://in-toto.io/Statement/v1\",\"createdAt\":\"2025-11-27T08:29:19.404Z\",\"createdBy\":\"create_dsse_user\",\"predicate\":{\"qa_status\":\"passed\",\"tester\":\"qa-team\",\"tests_executed\":42,\"tests_failed\":0,\"tests_passed\":42},\"predicateType\":\"https://sonar.com/evidence/sonarqube/v1\",\"stage\":\"QA\",\"subject\":[{\"digest\":{\"sha256\":\"a108ace8d991c6d2b09dd18fea91eb6a2b70a6341bff72638b051c43fe4286e3\"}}]}"
}

The response contains the following:

Parameter	Type	Description
`post_url`	string	The url to be used by the client to upload the DSSE payload after signing the in-toto payload returned by the `dsse_payload` parameter. For example: /evidence/api/v1/subject/generic-local/docs/readme.txt?providerId=jfrog
`dsse_payload`	base64 string	The encoded `payload` to be used in the DSSE entity containing all required parameters. Note If the evidence subject is an application version or Release Bundle v2 version, the payload will include the version's current stage. When you use the Deploy Evidence API, the evidence will be associated with this stage in the platform UI.Stages & Lifecycle
`dsse_payload_type`	string	The `payload_type` field to be used in the DSSE entity: "application/vnd.in-toto+json".
`pre_authentication_encoding`	string	Relevant only when the `include_pae` query parameter is set to `true`. The PAE consists of the DSSE version, the length of the payload_type, the text of the payload type, the length of the payload, and the decoded text of the payload.

Status Codes:

Code	Description
201	Created
401	Bad Credentials
403	Permission Denied
404	Not Found