Prepare a file upload
prepare_file_uploadGet an upload destination for a file your shell transfers directly.
Use this to keep a file out of the context window. Call the tool, run
upload_command against the local file, then pass the returned reference
to the consuming tool.
Attach the file by passing s3_url to create_project or update_project as
documents[].s3_url. For external_findings on a project with several
repositories, add documents[].repo_slug. Every later scan reads attached
findings.
Uploading again under the same file_name stores a new version. Attaching
it replaces the attached version, and the reply says so.
Use document_name for security_advisor content_document and get_artifact
design_doc.
The file is stored under document_type, and the attaching tools read the
type from s3_url. Do not upload source code as a document. Connect its
repository through create_project's github_repo.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"file_name": "<file_name>",
"document_type": "<document_type>",
"document_format": "<document_format>"
},
"name": "prepare_file_upload"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| digest | No | Optional content digest as 'sha256:<64 hex chars>' (compute with sha256sum). When it matches an already-stored version the upload is skipped and the existing location returned. | |
| file_name | Yes | Stored document name. Allowed characters are letters, digits, hyphens, underscores, and periods. | |
| document_type | Yes | 'design_doc' for design docs, specs, or plans; 'external_findings' for SARIF, Semgrep, or Snyk output from the customer's scanners. Do not upload source code as a document; connect its repository with github_repo. | |
| document_format | Yes | File format. design_doc: md or pdf; external_findings: sarif, semgrep_json, or snyk_json. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| error | No | True when the call itself failed. False for successful calls, including a scan still running, an already approved plan, or a repository classified as non-agentic. The reason field describes these workflow states. | |
| reason | No | A stable snake_case code from the allowed set. Present on every error and on successful calls that carry a workflow state. | |
| s3_url | No | Stable document location. Pass this as the document reference to create_project or update_project documents[].s3_url. | |
| message | No | Exactly one sentence written for the user. Never raw exception text or a backend error string, which may expose private details. | |
| metadata | No | Caller metadata, such as 'expiration_warning'. Substantive results have their own fields. Never includes exception or backend error text, which may expose private details. | |
| expires_at | No | ISO timestamp when the upload_url stops working. | |
| next_steps | No | Recommended next actions, in order. | |
| upload_url | No | Presigned PUT URL for the file bytes. None when skipped_upload is true because Trent already stores identical content. | |
| content_type | No | Content-Type header to send with the PUT. | |
| document_name | No | Stored document name, for security_advisor content_document and get_artifact design_doc. | |
| max_size_bytes | No | Server-enforced maximum file size for this document type. | |
| skipped_upload | No | True when the digest matched a stored version. The file is already available at s3_url, so use that reference directly. | |
| upload_command | No | Ready-to-run shell command template for the transfer; replace <local-file-path> with the file to upload. | |
| document_version | No | Version number assigned to this upload. | |
| retry_after_seconds | No | With reason rate_limited, how many seconds Trent asks the caller to wait. | |
| max_scan_total_bytes | No | For external_findings, the most findings-file bytes one scan reads across all the project's attached files. Files past it are skipped for that scan. Null for other document types. |