● Files · /v1

Files

Upload dispute evidence. Files are bound to one purpose — this is not general-purpose storage.

Upload a file

POST /v1/files

multipart/form-data, 10 MB per file, pdf / jpg / png / tiff only — the card networks reject anything else, so we block it up front rather than letting you lose the dispute.

Pass the returned uid in file_ids when submitting dispute evidence. Files are kept for 180 days.

Headers

Idempotency-Keyrequired string A unique string you generate (UUID/ULID recommended). Replaying the same key within 24 hours returns the original result and never creates a second payment.

Response 201

uid string
purpose dispute_evidence What the file is for, fixed at upload time
filename string
size integer Size in bytes. 10 MB per file
content_type string
created_at string<date-time>
expires_at string<date-time> Evidence is retained for 180 days, then purged automatically

Errors

400Invalid parameters
Request
curl -X POST https://api.baton.example/v1/files \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..."
Response · 201
{
  "uid": "file_9a21c7",
  "purpose": "dispute_evidence",
  "filename": "proof-of-delivery.pdf",
  "size": 284117,
  "content_type": "application/pdf",
  "created_at": "2026-11-16T09:42:00Z",
  "expires_at": "2027-05-15T09:42:00Z"
}

Retrieve file metadata

GET /v1/files/{uid}

Returns metadata only, never the contents. A file already submitted as evidence cannot be deleted, for audit reasons.

Path parameters

uidrequired string

Response 200

uid string
purpose dispute_evidence What the file is for, fixed at upload time
filename string
size integer Size in bytes. 10 MB per file
content_type string
created_at string<date-time>
expires_at string<date-time> Evidence is retained for 180 days, then purged automatically

Errors

404The object does not exist, or belongs to another environment or merchant
Request
curl -X GET https://api.baton.example/v1/files/{uid} \
  -H "Authorization: Bearer sk_live_xxx"