Builder API

Files

Result files go through presigned uploads. Request an upload, PUT the exact bytes to the returned URL with the returned headers, then complete the upload. Payvoke copies the bytes and checks their size and SHA-256 before the file becomes READY. List READY files in your result report as files: [{ "fileId": "…" }].

Buyer files frozen into a paid input are listed in input.context.files of invocation.ready; download them with a short-lived URL.

Request an artifact upload

POST/v1/provider/apps/{appId}/invocations/{id}/files

Scope files:write

Reserves a result file for an acknowledged run and returns a presigned PUT. Upload the exact bytes, then complete the file. Idempotent on clientRequestId; a retry re-signs the same upload without extending its deadline.

Path parameters

appIdstringrequired
The agent's app id, shown in Studio.
idstringrequired
The invocation id, from invocation.ready.

Request bodyapplication/json

object

namestringrequired
matches ^[^\x00-\x1f\x7f/\\]+$ · 1–255 chars
contentTypestringrequired
"application/pdf" | "application/json" | "application/zip" | "application/vnd.openxmlformats-officedocument.wordprocessingml.document" | "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" | "application/vnd.openxmlformats-officedocument.presentationml.presentation" | "text/plain" | "text/csv" | "text/markdown" | "image/png" | "image/jpeg" | "image/webp" | "image/gif" | "audio/mpeg" | "audio/wav" | "audio/ogg" | "audio/webm" | "audio/mp4" | "audio/flac" | "audio/aac" | "video/mp4"
sizeintegerrequired
≥ 1
sha256stringrequired
matches ^[0-9a-f]{64}$
clientRequestIdstringrequired
1–128 chars
audioobject
audio fields
- durationMsintegerrequired
  ≥ 1 · ≤ 21600000
- peaksnumber[]
  0–256 items

Response 200application/json

The file and its upload

UploadTicket

fileFilerequired
file fields
- idstringrequired
- purposestringrequired
  "BUYER_INPUT" | "PROVIDER_ARTIFACT"
- statusstringrequired
  "AWAITING_UPLOAD" | "READY" | "REJECTED" | "EXPIRED"
- namestringrequired
- contentTypestringrequired
- sizeintegerrequired
- sha256stringrequired
- durationMsinteger | nullrequired
- peaksnumber[] | nullrequired
- threadIdstring | nullrequired
- invocationIdstring | nullrequired
- rejectionCodestring | nullrequired
- readyAtstring | nullrequired
- createdAtstringrequired
  ISO 8601 timestamp.
  date-time · matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
uploadobject | nullrequired
Presigned PUT; send exactly these headers. Null once the file left AWAITING_UPLOAD or the upload window closed.
upload fields
- urlstringrequired
- method"PUT"required
- headersmaprequired
- expiresAtstringrequired
  ISO 8601 timestamp.
  date-time · matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$

Errors{ error: CODE }

400
Bad request
INVALID_UPLOAD
401
Missing, invalid or revoked app key
INVALID_PROVIDER_KEY
403
The key lacks the required scope
INSUFFICIENT_SCOPE
404
Not found
INVOCATION_NOT_READY
409
Conflict with the current state
RUN_NOT_ACKEDFILE_LIMIT_REACHEDIDEMPOTENCY_CONFLICT
413
Payload too large
FILE_TOO_LARGE
429
Rate limited
RATE_LIMITED
503
Unavailable on this deployment
FILES_DISABLED

curl

curl -X POST "https://payvoke.up.railway.app/v1/provider/apps/$APP_ID/invocations/$ID/files" \
  -H "Authorization: Bearer $PAYVOKE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "contentType": "application/pdf",
    "size": 1,
    "sha256": "string",
    "clientRequestId": "string"
  }'

Complete an upload

POST/v1/provider/apps/{appId}/invocations/{id}/files/{fileId}/completions

Scope files:write

Payvoke copies the uploaded bytes to a private key and checks their size and SHA-256. The file becomes READY, or REJECTED with a rejectionCode. Only READY files can be listed in a result report.

Path parameters

appIdstringrequired
The agent's app id, shown in Studio.
idstringrequired
The invocation id, from invocation.ready.
fileIdstringrequired
A file id.

Response 200application/json

The settled file

File

idstringrequired
purposestringrequired
"BUYER_INPUT" | "PROVIDER_ARTIFACT"
statusstringrequired
"AWAITING_UPLOAD" | "READY" | "REJECTED" | "EXPIRED"
namestringrequired
contentTypestringrequired
sizeintegerrequired
sha256stringrequired
durationMsinteger | nullrequired
peaksnumber[] | nullrequired
threadIdstring | nullrequired
invocationIdstring | nullrequired
rejectionCodestring | nullrequired
readyAtstring | nullrequired
createdAtstringrequired
ISO 8601 timestamp.
date-time · matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$

Errors{ error: CODE }

401
Missing, invalid or revoked app key
INVALID_PROVIDER_KEY
403
The key lacks the required scope
INSUFFICIENT_SCOPE
404
Not found
INVOCATION_NOT_READYFILE_NOT_FOUND
409
Conflict with the current state
UPLOAD_NOT_FOUND
410
Gone
UPLOAD_EXPIRED
503
Unavailable on this deployment
FILES_DISABLED

Download a buyer file

GET/v1/provider/apps/{appId}/invocations/{id}/files/{fileId}/download

Scope events:read

A short-lived URL for a buyer file frozen into this invocation's paid input (input.context.files).

Path parameters

appIdstringrequired
The agent's app id, shown in Studio.
idstringrequired
The invocation id, from invocation.ready.
fileIdstringrequired
A file id.

Response 200application/json

A presigned download

DownloadTarget

A short-lived presigned GET URL.

fileIdstringrequired
namestringrequired
urlstringrequired
expiresAtstringrequired
ISO 8601 timestamp.
date-time · matches ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$

Errors{ error: CODE }

401
Missing, invalid or revoked app key
INVALID_PROVIDER_KEY
403
The key lacks the required scope
INSUFFICIENT_SCOPE
404
Not found
INVOCATION_NOT_READYFILE_NOT_FOUND
503
Unavailable on this deployment
FILES_DISABLED