curl -X POST https://win.oneshotagent.com/v1/tools/physical-mail/assets \
-H "Content-Type: application/pdf" \
-H "X-Agent-ID: 0xYourWalletAddress" \
-H "x-agent-proof: <base64 signed proof, scope=write>" \
--data-binary @letter.pdf
import { OneShot } from "@oneshot-agent/sdk";
const agent = new OneShot({ privateKey: process.env.AGENT_PRIVATE_KEY });
const asset = await agent.physicalMail.uploadArtwork(pdfBytes, "application/pdf");
console.log(asset.asset_id);
asset = client.physical_mail.upload_artwork(pdf_bytes, "application/pdf")
print(asset["asset_id"])
{
"asset_id": "00000000-0000-4000-8000-000000000000",
"content_hash": "<sha-256 hex>",
"mime_type": "application/pdf"
}
{
"error": "invalid_artwork"
}
Physical Mail
Upload artwork
Upload immutable print-ready artwork for a letter or a postcard
POST
/
v1
/
tools
/
physical-mail
/
assets
curl -X POST https://win.oneshotagent.com/v1/tools/physical-mail/assets \
-H "Content-Type: application/pdf" \
-H "X-Agent-ID: 0xYourWalletAddress" \
-H "x-agent-proof: <base64 signed proof, scope=write>" \
--data-binary @letter.pdf
import { OneShot } from "@oneshot-agent/sdk";
const agent = new OneShot({ privateKey: process.env.AGENT_PRIVATE_KEY });
const asset = await agent.physicalMail.uploadArtwork(pdfBytes, "application/pdf");
console.log(asset.asset_id);
asset = client.physical_mail.upload_artwork(pdf_bytes, "application/pdf")
print(asset["asset_id"])
{
"asset_id": "00000000-0000-4000-8000-000000000000",
"content_hash": "<sha-256 hex>",
"mime_type": "application/pdf"
}
{
"error": "invalid_artwork"
}
Overview
Stores one print-ready file and returns itsasset_id. The body is the raw file, not JSON or a form. A letter takes a PDF of 1 to 60 pages. A postcard side takes a PDF, PNG or JPEG. 20 MB maximum. A stored asset never changes. Free.
Pass the asset_id to Preview as artwork.file (letter) or artwork.front and artwork.back (postcard).
Authentication
X-Agent-ID plus a signed x-agent-proof with scope: "write", or an access token. See proof authentication. 60 requests a minute per agent.
Headers
string
required
application/pdf, image/png or image/jpeg. The bytes must be that type.Request Body
The raw bytes of the file. Maximum 20 MB.Response
string
Asset ID to reference from a preview
string
SHA-256 of the uploaded bytes, hex encoded
string
The
Content-Type the file was stored withcurl -X POST https://win.oneshotagent.com/v1/tools/physical-mail/assets \
-H "Content-Type: application/pdf" \
-H "X-Agent-ID: 0xYourWalletAddress" \
-H "x-agent-proof: <base64 signed proof, scope=write>" \
--data-binary @letter.pdf
import { OneShot } from "@oneshot-agent/sdk";
const agent = new OneShot({ privateKey: process.env.AGENT_PRIVATE_KEY });
const asset = await agent.physicalMail.uploadArtwork(pdfBytes, "application/pdf");
console.log(asset.asset_id);
asset = client.physical_mail.upload_artwork(pdf_bytes, "application/pdf")
print(asset["asset_id"])
{
"asset_id": "00000000-0000-4000-8000-000000000000",
"content_hash": "<sha-256 hex>",
"mime_type": "application/pdf"
}
{
"error": "invalid_artwork"
}
Errors
| Code | When |
|---|---|
400 invalid_artwork | Empty body, over 20 MB, unsupported Content-Type, or bytes that are not that type |
503 physical_mail_not_configured | Not available yet |