GuidesUpload Evidence

Upload Evidence

Use the Scrut API to upload files to an evidence task from your scripts, CI/CD pipelines, or backend services.

You can upload evidence files to Scrut from your own scripts, CI/CD pipelines, or backend services instead of adding them manually in the product. This guide shows you how to find the evidence task you want, upload one or more files to it, and verify that the upload worked.

Files you upload through the API are handled the same way as files you upload manually in Scrut. See Upload Evidence Manually in the Scrut Help Center.

Before You Begin

You need:

  • A Read & Write credential, created by an Org Admin in Settings → Developer Console in Scrut. Uploading attachments requires the evidence:write scope, which only Read & Write credentials have. See Create API Credentials.
  • An access token requested with that credential. Confirm that the scope field in the token response includes evidence:write. See the API Quickstart.
  • The evidence files you want to upload, saved locally in a supported file type.

The examples use https://api.scrut.io. Replace it with your region's base URL.

Uploading evidence on a recurring schedule, such as quarterly access reviews? Run the same three calls below from a cron job or a CI/CD step.

Find the evidence task

Call GET /v1/evidence and narrow the results with filters to find the evidence task you want to upload to.

curl "https://api.scrut.io/v1/evidence?frameworkIds=14c4c45d-6c31-4097-a02a-ad9cfd04850e&status=not_uploaded,needs_attention" \
  -H "Authorization: Bearer $SCRUT_ACCESS_TOKEN"

Response (truncated):

{
  "data": [
    {
      "evidenceId": "92af7e7f-b18e-495b-bf92-61c23ebd34a7",
      "evidenceName": "Quarterly Access Review",
      ...
    }
  ]
}

Copy the evidenceId. You send it as the path parameter in the next step. The evidence list isn't paginated, so it returns every matching evidence task in a single array.

Store the evidenceId for each evidence task your job uploads to, so later runs don't need to look it up again.

Upload the files

Call POST /v1/evidence/{evidenceId}/attachments as multipart/form-data.

Before you upload, check your files against these rules:

RuleLimit
Files per requestUp to 5
Size per requestThe combined size of all files in one request can't exceed 100 MB.
File typesSee Supported File Types.

Send these fields in the request body:

FieldRequiredDescription
filesYesOne file per files field. Repeat the field for each file, up to five per request.
evidenceDateYesThe evidence date, as Unix epoch milliseconds. You can send it as a number or a numeric string. Can't be in the future.
noteNoA note stored with the upload.

Each upload also needs an Idempotency-Key header. Generate one key per upload and store it with the upload's record in your job. If the request fails with a network error, a timeout, a 429, or a 5xx status, retry it with the same key and the same body so Scrut doesn't upload the files twice.

curl -X POST "https://api.scrut.io/v1/evidence/92af7e7f-b18e-495b-bf92-61c23ebd34a7/attachments" \
  -H "Authorization: Bearer $SCRUT_ACCESS_TOKEN" \
  -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -F "evidenceDate=1715904000000" \
  -F "note=Q2 access review, identity verification records" \
  -F "files=@access-review.pdf" \
  -F "files=@appendix.pdf"

Expected response (201):

{
  "data": {
    "evidenceId": "92af7e7f-b18e-495b-bf92-61c23ebd34a7",
    "modifiedOn": 1711929600000
  },
  "meta": {
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

If you retry with the same key and body within 24 hours, Scrut returns the stored response with the header Idempotent-Replayed: true and doesn't upload the files again. See Idempotency.

Verify the upload

Call GET /v1/evidence/{evidenceId} with attachments in fields to confirm the files were attached.

curl "https://api.scrut.io/v1/evidence/92af7e7f-b18e-495b-bf92-61c23ebd34a7?fields=attachments" \
  -H "Authorization: Bearer $SCRUT_ACCESS_TOKEN"

Each item in attachments includes:

FieldDescription
displayNameThe file name, such as access-review.pdf.
typeFile, Link, or Inline.
evidenceDateThe evidence date, as Unix epoch milliseconds.
noteThe note stored with the upload, if any.
addedBy, addedOnWho added the attachment and when.
isCurrentPeriodWhether the attachment belongs to the current evidence period.
periodStart, periodEndThe start and end of the evidence period the attachment belongs to.

The response doesn't include download URLs for files hosted by Scrut.

Note: The API accepts only file uploads and doesn't provide an endpoint to delete or replace an attachment. To add evidence from an external link, use Add Attachment → Use a Link in Scrut.

Supported File Types

TypeExtensions
PDF.pdf
Word.doc, .docx, .dotx
Excel.xls, .xlsx, .xlsm
PowerPoint.ppt, .pptx
Text.txt, .log, .html
Markdown.md
YAML.yaml, .yml
CSV.csv
JSON.json
XML.xml
ImagesAny image type, such as PNG, JPG, GIF, SVG
Video.mp4, .avi
Audio.mp3, .wav
Archives.zip, .rar
Apple iWork.numbers, .pages
Email.eml, .msg
Other.dwf, .evtx

Congratulations

You've uploaded files to a Scrut evidence task and confirmed that they were attached. Scrut organizes the files into a date-specific folder based on the evidence date, following the fiscal year format set in Settings. See Upload Evidence Manually.

Contact support@scrut.io for further assistance.