Files
Manage Environment and Persona files using the public API.
All routes below use /v1/projects/{projectId}/files. Project UUIDs and file UUIDs are required. Credentials inherit current project permissions and need read or write scope for the corresponding operations.
| Method | Suffix | Purpose |
|---|---|---|
| GET | ?scope=environment&ownerId=UUID | List ready files for an Environment; use scope=persona for a Persona |
| POST | empty | Initiate a new upload |
| GET | /{id} | Get metadata |
| PATCH | /{id} | Edit name and/or description |
| DELETE | /{id} | Remove from future executions |
| POST | /{id}/uploads | Initiate replacement |
| POST | /{id}/uploads/{uploadId}/complete | Verify and publish uploaded bytes |
| GET | /{id}/preview?page=1&offset=0 | Bounded preview |
| GET | /{id}/download | Original bytes as an authenticated attachment |
| GET | /runs/{runId} | Frozen manifest, content availability and read/upload usage |
| GET | /runs/{runId}/{id}/preview | Preview the exact historical version |
| GET | /runs/{runId}/{id}/download | Download the exact historical version |
Upload
Initiate with the file's byte size and lowercase hexadecimal SHA-256:
{
"scope": "environment",
"ownerId": "11111111-1111-4111-8111-111111111111",
"filename": "invoice.pdf",
"mimeType": "application/pdf",
"size": 12345,
"checksum": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
"name": "Sample invoice",
"description": "Use for invoice import tests."
}The response contains fileId, uploadId, url, method: "PUT", required headers, and expiresIn: 600. PUT the original bytes directly to that URL using the returned headers, without your Smoketest API key. Then call the completion endpoint with your API key. The file becomes ready only after size and checksum verification. The signed URL is temporary and must not be stored in Test instructions.
For replacement, send the same content metadata to /{id}/uploads, omitting owner scope. Ownership cannot change. Replacements preserve the file ID and publish a new immutable version. One replacement can be pending at a time. An expired/abandoned reservation is reclaimed automatically; initiate a new upload after expiry.
Limits: 25 MiB per file and 5 GiB of current files per project. Replacements reserve positive growth; old versions needed by unfinished work do not count against the current-file quota. Quota and validation errors use 400; conflicting/expired reservations use 409. Missing/out-of-scope Test references reject dispatch with 422. Storage failures use 503.
Preview and history
Preview responses contain a kind, bounded text and/or base64 JPEG image, optional page/pages, offset/nextOffset, and truncated. PDF pages are one-based. Text offsets are UTF-8 bytes; PDF text offsets address the selected page's extracted text. Follow nextOffset on the same page. unsupported or unavailable includes a reason and leaves original bytes uploadable.
Historical manifests never substitute current bytes for reclaimed versions. contentsAvailable: false means preview/download is no longer available. Run-file routes also enforce Run/source visibility.
File references use [label](smoketest-file:UUID) in Test Markdown. Individual Test create/get/update responses include fileDiagnostics for missing/out-of-scope references. Incomplete Tests can be saved; execution validates again before dispatch and charging. No new MCP tools are included.
Run-file history may include scope: "ticket" and ticket provenance (provider, ticket identity, and known description/comment origins). Management endpoints continue to accept only Environment and Persona scopes. Usage distinguishes metadata disclosure (list), inspection (read), and upload (upload), with timestamps and inspection evidence IDs when recorded. No public Attempt-management interface is introduced.