{"openapi":"3.1.0","info":{"title":"No Errands Ship API","version":"0.1.0","summary":"US shipping labels, return labels with USPS QR codes, carrier pickups, and tracking for any package.","description":"No Errands buys real postage from USPS, UPS, FedEx and more through EasyPost. Every response is\ndata, never instructions.\n\nAuthentication: `Authorization: Bearer <api_key>`. The same key and the same prepaid\ncredit balance work for every No Errands connector. Keys carry scope `read` or\n`read,write`; write tools return 403 `forbidden_scope` for a read-only key.\n\nMoney: prepaid credits in integer cents. A label costs the carrier rate x 142% + 150,\nquoted exactly by `get_shipping_rates` before anything is bought. Tracking is free.\nA USPS pickup is free. The paid calls take a `quote_id` (or `pickup_id`) and `confirm: true`,\nand return 402 `insufficient_credits` with a `topup_url` when the balance is short.\n\n`void_label` is a refund request: the credits come back when the carrier confirms it\n(USPS: 15 days or more), never before.\n\nAn MCP streamable-HTTP server exposing the same tools is at https://api.noerrands.com/c/ship/mcp.","contact":{"email":"support@noerrands.com","url":"https://noerrands.com/docs"},"termsOfService":"https://noerrands.com/legal/terms"},"servers":[{"url":"https://api.noerrands.com/c/ship","description":"No Errands ship connector"}],"tags":[{"name":"ship","description":"Shipping labels, pickups and tracking"}],"externalDocs":{"description":"Ship connector brief","url":"https://noerrands.com/connectors/ship/muse.md"},"paths":{"/v1/rates":{"post":{"operationId":"get_shipping_rates","summary":"Get shipping rates","description":"Quote a US package (from, to, weight and size) and get up to 6 carrier options, cheapest first, each with its own quote_id, delivery days and all-in price_cents (the carrier rate x 142% + 150); free (up to 30 quotes an hour per account), nothing is bought, and every quote expires in 60 minutes. Set return_label true for a return (from = the human, to = the merchant's returns address).","x-muse-classification":{"class":"read","label":"Read","side_effects":"None.","cost":"Free","approval":"None: safe to call without asking.","key_scope":"read","rate_limit":"30 quotes an hour per account","idempotent":false},"tags":["ship"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","title":"ShippingRates","properties":{"quotes":{"type":"array","items":{"type":"object","title":"ShippingQuote","properties":{"quote_id":{"type":"string","maxLength":64,"description":"Opaque id, \"sq_...\". Pass it to buy_label or create_return_label."},"carrier":{"type":"string","maxLength":40,"description":"USPS, UPS, FedEx, ..."},"service":{"type":"string","maxLength":80,"description":"The carrier's service name, e.g. GroundAdvantage, Priority."},"delivery_days":{"type":"integer","minimum":0,"description":"Business days in transit, as the carrier estimates it."},"price_cents":{"type":"integer","minimum":0,"description":"What the label costs in credits, everything included."},"retail_cents":{"type":"integer","minimum":0,"description":"What the same label costs over a post office counter, when the carrier reports it. For comparison only."},"qr_code_available":{"type":"boolean","description":"True for USPS: the label can come as a QR code the human shows at a post office instead of printing."}},"required":["quote_id","carrier","service","price_cents","qr_code_available"],"additionalProperties":false},"description":"Cheapest first, at most 6."},"expires_at":{"type":"string","format":"date-time","description":"Every quote above can be bought until then (60 minutes)."},"return_label":{"type":"boolean"},"address_notes":{"type":"array","items":{"type":"string"}},"balance_cents":{"type":"integer","description":"General credit available right now."}},"required":["quotes","expires_at","return_label","address_notes","balance_cents"],"additionalProperties":false}}}},"400":{"description":"invalid_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized. Carries WWW-Authenticate: Bearer resource_metadata=\"...\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"forbidden_scope: a write tool called with a read-only key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"provider_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"from":{"type":"object","title":"ShipAddress","description":"Where the package starts. For a return, the human sending it back.","properties":{"name":{"type":"string","maxLength":40,"minLength":1,"description":"Recipient or sender name, 1-40 characters."},"company":{"type":"string","maxLength":40,"description":"Optional company line, up to 40 characters."},"line1":{"type":"string","maxLength":64,"minLength":1,"description":"Street address, up to 64 characters."},"line2":{"type":"string","maxLength":64,"description":"Apartment, suite, or unit, up to 64 characters."},"city":{"type":"string","maxLength":200,"minLength":1},"state":{"type":"string","maxLength":2,"minLength":2,"pattern":"^[A-Za-z]{2}$","description":"Two-letter US state code."},"zip":{"type":"string","pattern":"^[0-9]{5}(-?[0-9]{4})?$","description":"ZIP code, 5 digits or ZIP+4."},"country":{"type":"string","enum":["US"],"default":"US","description":"US only in v0."},"phone":{"type":"string","maxLength":20,"pattern":"^[0-9+()\\-. ]{7,20}$","description":"Optional. Some carriers print it or call it about a delivery problem."},"email":{"type":"string","maxLength":254,"description":"Optional. Some carriers send delivery notices to it."}},"required":["name","line1","city","state","zip"],"additionalProperties":false},"to":{"type":"object","title":"ShipAddress","description":"Where it goes. For a return, the merchant's returns address, exactly as the merchant gives it.","properties":{"name":{"type":"string","maxLength":40,"minLength":1,"description":"Recipient or sender name, 1-40 characters."},"company":{"type":"string","maxLength":40,"description":"Optional company line, up to 40 characters."},"line1":{"type":"string","maxLength":64,"minLength":1,"description":"Street address, up to 64 characters."},"line2":{"type":"string","maxLength":64,"description":"Apartment, suite, or unit, up to 64 characters."},"city":{"type":"string","maxLength":200,"minLength":1},"state":{"type":"string","maxLength":2,"minLength":2,"pattern":"^[A-Za-z]{2}$","description":"Two-letter US state code."},"zip":{"type":"string","pattern":"^[0-9]{5}(-?[0-9]{4})?$","description":"ZIP code, 5 digits or ZIP+4."},"country":{"type":"string","enum":["US"],"default":"US","description":"US only in v0."},"phone":{"type":"string","maxLength":20,"pattern":"^[0-9+()\\-. ]{7,20}$","description":"Optional. Some carriers print it or call it about a delivery problem."},"email":{"type":"string","maxLength":254,"description":"Optional. Some carriers send delivery notices to it."}},"required":["name","line1","city","state","zip"],"additionalProperties":false},"parcel":{"type":"object","title":"Parcel","description":"The package. weight_oz is always required. Then either all three dimensions in inches, or a preset, or neither (the carrier then prices by weight).","properties":{"weight_oz":{"type":"number","minimum":0.1,"maximum":1120,"description":"Weight in ounces, packed. 16 oz = 1 lb. Use what the human says it weighs."},"length_in":{"type":"number","minimum":0.1,"maximum":108,"description":"Inches."},"width_in":{"type":"number","minimum":0.1,"maximum":108,"description":"Inches."},"height_in":{"type":"number","minimum":0.1,"maximum":108,"description":"Inches."},"preset":{"type":"string","enum":["envelope","small_box","medium_box","large_box","flat_rate_envelope","small_flat_rate_box","medium_flat_rate_box","large_flat_rate_box"],"description":"Instead of dimensions: envelope (padded envelope, 12 x 9.5 x 1 in); small_box (small box, 9 x 6 x 3 in); medium_box (medium box, 12 x 10 x 6 in); large_box (large box, 18 x 14 x 10 in); flat_rate_envelope (USPS Priority Mail flat rate envelope); small_flat_rate_box (USPS Priority Mail small flat rate box); medium_flat_rate_box (USPS Priority Mail medium flat rate box); large_flat_rate_box (USPS Priority Mail large flat rate box). Flat rate presets are priced by USPS Priority Mail only."}},"required":["weight_oz"],"additionalProperties":false},"return_label":{"type":"boolean","default":false,"description":"True for a return label (then use create_return_label to buy it)."}},"required":["from","to","parcel"],"additionalProperties":false}}}}}},"/v1/labels":{"post":{"operationId":"buy_label","summary":"Buy a shipping label","description":"Buy the outbound shipping label for one quote_id, with confirm true; CONSEQUENTIAL -- it charges that quote's price_cents in credits and buys real postage -- and returns the printable label_url (PDF) and the tracking number, plus a USPS QR code if qr_code is true. Sensitive write: it requires the human's approval of that quote's carrier, delivery days and price. A short balance returns 402 with a topup_url. A replay with the same idempotency_key returns the original label and never buys twice.","x-muse-classification":{"class":"sensitive_write","label":"Sensitive write","side_effects":"Buys real postage from the carrier and debits the quote's price in credits.","cost":"The quote's price_cents: carrier rate x 142% + 150","approval":"Explicit approval of the carrier, delivery days and price of that quote.","key_scope":"write","idempotent":false},"tags":["ship"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","title":"LabelResult","properties":{"shipment_id":{"type":"string","maxLength":64,"description":"Opaque id, \"sh_...\". Use it with get_shipment."},"kind":{"type":"string","enum":["outbound","return"]},"status":{"type":"string","enum":["unknown","pre_transit","in_transit","out_for_delivery","delivered","available_for_pickup","return_to_sender","failure","cancelled","error"],"description":"The carrier's tracking status. pre_transit means the label exists and nothing has been scanned yet."},"carrier":{"type":"string","maxLength":40},"service":{"type":"string","maxLength":80},"tracking_code":{"type":"string","maxLength":64},"label_url":{"type":"string","format":"uri","description":"The printable PDF label. Gone after the retention window."},"qr_code_url":{"type":"string","format":"uri","description":"USPS QR code image. The human shows it at a post office counter and the clerk prints the label."},"tracking_url":{"type":"string","format":"uri","description":"The carrier's public tracking page."},"est_delivery_date":{"type":"string","maxLength":40},"credits_charged_cents":{"type":"integer","minimum":0,"description":"Net credits this label cost: zero once a refund has been confirmed."},"refund_status":{"type":"string","enum":["none","submitted","refunded","rejected"],"description":"none, or after void_label: submitted (waiting on the carrier), refunded (credits are back), rejected (the label was used or too old)."},"from":{"type":"object","title":"StoredAddress","description":"A US postal address as stored. After the 30-day retention window only city, state and the first 3 ZIP digits remain; name, company and street lines are permanently removed.","properties":{"name":{"type":"string","maxLength":40,"minLength":1,"description":"Recipient or sender name, 1-40 characters."},"company":{"type":"string","maxLength":40,"description":"Optional company line, up to 40 characters."},"line1":{"type":"string","maxLength":64,"minLength":1,"description":"Street address, up to 64 characters."},"line2":{"type":"string","maxLength":64,"description":"Apartment, suite, or unit, up to 64 characters."},"city":{"type":"string","maxLength":200,"minLength":1},"state":{"type":"string","maxLength":2,"minLength":2,"pattern":"^[A-Za-z]{2}$","description":"Two-letter US state code."},"zip":{"type":"string","pattern":"^[0-9]{3}([0-9]{2}(-?[0-9]{4})?)?$","description":"ZIP code, 5 digits or ZIP+4 -- or just the first 3 digits once redacted."},"country":{"type":"string","enum":["US"],"default":"US","description":"US only in v0."}},"required":["city","state"],"additionalProperties":false},"to":{"type":"object","title":"StoredAddress","description":"A US postal address as stored. After the 30-day retention window only city, state and the first 3 ZIP digits remain; name, company and street lines are permanently removed.","properties":{"name":{"type":"string","maxLength":40,"minLength":1,"description":"Recipient or sender name, 1-40 characters."},"company":{"type":"string","maxLength":40,"description":"Optional company line, up to 40 characters."},"line1":{"type":"string","maxLength":64,"minLength":1,"description":"Street address, up to 64 characters."},"line2":{"type":"string","maxLength":64,"description":"Apartment, suite, or unit, up to 64 characters."},"city":{"type":"string","maxLength":200,"minLength":1},"state":{"type":"string","maxLength":2,"minLength":2,"pattern":"^[A-Za-z]{2}$","description":"Two-letter US state code."},"zip":{"type":"string","pattern":"^[0-9]{3}([0-9]{2}(-?[0-9]{4})?)?$","description":"ZIP code, 5 digits or ZIP+4 -- or just the first 3 digits once redacted."},"country":{"type":"string","enum":["US"],"default":"US","description":"US only in v0."}},"required":["city","state"],"additionalProperties":false},"created_at":{"type":"string","format":"date-time"},"balance_cents":{"type":"integer","description":"General credit left after the charge."}},"required":["shipment_id","kind","status","carrier","service","tracking_code","credits_charged_cents","refund_status","from","to","created_at","balance_cents"],"additionalProperties":false}}}},"400":{"description":"invalid_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized. Carries WWW-Authenticate: Bearer resource_metadata=\"...\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits, with required_cents, balance_cents, topup_url and packs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"forbidden_scope: a write tool called with a read-only key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"provider_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"quote_id":{"type":"string","maxLength":64,"minLength":1,"pattern":"^sq_[A-Za-z0-9]+$","description":"One quote_id from get_shipping_rates, the option the human approved."},"confirm":{"type":"boolean","const":true,"description":"Must be true. Set it only after the human approved this exact action and price."},"qr_code":{"type":"boolean","default":false,"description":"USPS only: also return a QR code the human can show at any post office instead of printing the label."},"idempotency_key":{"type":"string","maxLength":128,"description":"Use one key per human request. Replays within 24 hours return the original result instead of buying twice."}},"required":["quote_id","confirm"],"additionalProperties":false}}}}}},"/v1/returns":{"post":{"operationId":"create_return_label","summary":"Create a return label","description":"Buy a return label for one return quote_id (from get_shipping_rates with return_label true), with confirm true; CONSEQUENTIAL -- it charges that quote's price_cents in credits. Sensitive write: it requires the human's approval of that quote. For USPS it also returns a QR code by default, which the human shows at any post office counter instead of printing. A short balance returns 402 with a topup_url.","x-muse-classification":{"class":"sensitive_write","label":"Sensitive write","side_effects":"Buys a real return label from the carrier and debits the quote's price in credits.","cost":"The quote's price_cents: carrier rate x 142% + 150","approval":"Explicit approval of the carrier, delivery days and price of that quote.","key_scope":"write","idempotent":false},"tags":["ship"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","title":"LabelResult","properties":{"shipment_id":{"type":"string","maxLength":64,"description":"Opaque id, \"sh_...\". Use it with get_shipment."},"kind":{"type":"string","enum":["outbound","return"]},"status":{"type":"string","enum":["unknown","pre_transit","in_transit","out_for_delivery","delivered","available_for_pickup","return_to_sender","failure","cancelled","error"],"description":"The carrier's tracking status. pre_transit means the label exists and nothing has been scanned yet."},"carrier":{"type":"string","maxLength":40},"service":{"type":"string","maxLength":80},"tracking_code":{"type":"string","maxLength":64},"label_url":{"type":"string","format":"uri","description":"The printable PDF label. Gone after the retention window."},"qr_code_url":{"type":"string","format":"uri","description":"USPS QR code image. The human shows it at a post office counter and the clerk prints the label."},"tracking_url":{"type":"string","format":"uri","description":"The carrier's public tracking page."},"est_delivery_date":{"type":"string","maxLength":40},"credits_charged_cents":{"type":"integer","minimum":0,"description":"Net credits this label cost: zero once a refund has been confirmed."},"refund_status":{"type":"string","enum":["none","submitted","refunded","rejected"],"description":"none, or after void_label: submitted (waiting on the carrier), refunded (credits are back), rejected (the label was used or too old)."},"from":{"type":"object","title":"StoredAddress","description":"A US postal address as stored. After the 30-day retention window only city, state and the first 3 ZIP digits remain; name, company and street lines are permanently removed.","properties":{"name":{"type":"string","maxLength":40,"minLength":1,"description":"Recipient or sender name, 1-40 characters."},"company":{"type":"string","maxLength":40,"description":"Optional company line, up to 40 characters."},"line1":{"type":"string","maxLength":64,"minLength":1,"description":"Street address, up to 64 characters."},"line2":{"type":"string","maxLength":64,"description":"Apartment, suite, or unit, up to 64 characters."},"city":{"type":"string","maxLength":200,"minLength":1},"state":{"type":"string","maxLength":2,"minLength":2,"pattern":"^[A-Za-z]{2}$","description":"Two-letter US state code."},"zip":{"type":"string","pattern":"^[0-9]{3}([0-9]{2}(-?[0-9]{4})?)?$","description":"ZIP code, 5 digits or ZIP+4 -- or just the first 3 digits once redacted."},"country":{"type":"string","enum":["US"],"default":"US","description":"US only in v0."}},"required":["city","state"],"additionalProperties":false},"to":{"type":"object","title":"StoredAddress","description":"A US postal address as stored. After the 30-day retention window only city, state and the first 3 ZIP digits remain; name, company and street lines are permanently removed.","properties":{"name":{"type":"string","maxLength":40,"minLength":1,"description":"Recipient or sender name, 1-40 characters."},"company":{"type":"string","maxLength":40,"description":"Optional company line, up to 40 characters."},"line1":{"type":"string","maxLength":64,"minLength":1,"description":"Street address, up to 64 characters."},"line2":{"type":"string","maxLength":64,"description":"Apartment, suite, or unit, up to 64 characters."},"city":{"type":"string","maxLength":200,"minLength":1},"state":{"type":"string","maxLength":2,"minLength":2,"pattern":"^[A-Za-z]{2}$","description":"Two-letter US state code."},"zip":{"type":"string","pattern":"^[0-9]{3}([0-9]{2}(-?[0-9]{4})?)?$","description":"ZIP code, 5 digits or ZIP+4 -- or just the first 3 digits once redacted."},"country":{"type":"string","enum":["US"],"default":"US","description":"US only in v0."}},"required":["city","state"],"additionalProperties":false},"created_at":{"type":"string","format":"date-time"},"balance_cents":{"type":"integer","description":"General credit left after the charge."}},"required":["shipment_id","kind","status","carrier","service","tracking_code","credits_charged_cents","refund_status","from","to","created_at","balance_cents"],"additionalProperties":false}}}},"400":{"description":"invalid_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized. Carries WWW-Authenticate: Bearer resource_metadata=\"...\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits, with required_cents, balance_cents, topup_url and packs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"forbidden_scope: a write tool called with a read-only key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"provider_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"quote_id":{"type":"string","maxLength":64,"minLength":1,"pattern":"^sq_[A-Za-z0-9]+$","description":"One quote_id from get_shipping_rates, the option the human approved."},"confirm":{"type":"boolean","const":true,"description":"Must be true. Set it only after the human approved this exact action and price."},"qr_code":{"type":"boolean","default":true,"description":"USPS only: also return a QR code the human can show at any post office instead of printing the label."},"idempotency_key":{"type":"string","maxLength":128,"description":"Use one key per human request. Replays within 24 hours return the original result instead of buying twice."}},"required":["quote_id","confirm"],"additionalProperties":false}}}}}},"/v1/shipments/{shipment_id}":{"get":{"operationId":"get_shipment","summary":"Get shipment","description":"Look up one label by shipment_id with its tracking status, label and QR links, refund status and history, refreshed from the carrier. Free. When the carrier has confirmed a refund requested with void_label, this call credits the label price back to the balance, once.","x-muse-classification":{"class":"write","label":"Write","side_effects":"Refreshes the stored status from the provider, and credits the label price back, once, when the carrier confirms a refund requested with void_label.","cost":"Free","approval":"None: the only ledger change is a refund in the human's favour.","key_scope":"read","idempotent":true},"tags":["ship"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"shipment_id":{"type":"string","maxLength":64,"description":"Opaque id, \"sh_...\". Use it with get_shipment."},"kind":{"type":"string","enum":["outbound","return"]},"status":{"type":"string","enum":["unknown","pre_transit","in_transit","out_for_delivery","delivered","available_for_pickup","return_to_sender","failure","cancelled","error"],"description":"The carrier's tracking status. pre_transit means the label exists and nothing has been scanned yet."},"carrier":{"type":"string","maxLength":40},"service":{"type":"string","maxLength":80},"tracking_code":{"type":"string","maxLength":64},"label_url":{"type":"string","format":"uri","description":"The printable PDF label. Gone after the retention window."},"qr_code_url":{"type":"string","format":"uri","description":"USPS QR code image. The human shows it at a post office counter and the clerk prints the label."},"tracking_url":{"type":"string","format":"uri","description":"The carrier's public tracking page."},"est_delivery_date":{"type":"string","maxLength":40},"credits_charged_cents":{"type":"integer","minimum":0,"description":"Net credits this label cost: zero once a refund has been confirmed."},"refund_status":{"type":"string","enum":["none","submitted","refunded","rejected"],"description":"none, or after void_label: submitted (waiting on the carrier), refunded (credits are back), rejected (the label was used or too old)."},"from":{"type":"object","title":"StoredAddress","description":"A US postal address as stored. After the 30-day retention window only city, state and the first 3 ZIP digits remain; name, company and street lines are permanently removed.","properties":{"name":{"type":"string","maxLength":40,"minLength":1,"description":"Recipient or sender name, 1-40 characters."},"company":{"type":"string","maxLength":40,"description":"Optional company line, up to 40 characters."},"line1":{"type":"string","maxLength":64,"minLength":1,"description":"Street address, up to 64 characters."},"line2":{"type":"string","maxLength":64,"description":"Apartment, suite, or unit, up to 64 characters."},"city":{"type":"string","maxLength":200,"minLength":1},"state":{"type":"string","maxLength":2,"minLength":2,"pattern":"^[A-Za-z]{2}$","description":"Two-letter US state code."},"zip":{"type":"string","pattern":"^[0-9]{3}([0-9]{2}(-?[0-9]{4})?)?$","description":"ZIP code, 5 digits or ZIP+4 -- or just the first 3 digits once redacted."},"country":{"type":"string","enum":["US"],"default":"US","description":"US only in v0."}},"required":["city","state"],"additionalProperties":false},"to":{"type":"object","title":"StoredAddress","description":"A US postal address as stored. After the 30-day retention window only city, state and the first 3 ZIP digits remain; name, company and street lines are permanently removed.","properties":{"name":{"type":"string","maxLength":40,"minLength":1,"description":"Recipient or sender name, 1-40 characters."},"company":{"type":"string","maxLength":40,"description":"Optional company line, up to 40 characters."},"line1":{"type":"string","maxLength":64,"minLength":1,"description":"Street address, up to 64 characters."},"line2":{"type":"string","maxLength":64,"description":"Apartment, suite, or unit, up to 64 characters."},"city":{"type":"string","maxLength":200,"minLength":1},"state":{"type":"string","maxLength":2,"minLength":2,"pattern":"^[A-Za-z]{2}$","description":"Two-letter US state code."},"zip":{"type":"string","pattern":"^[0-9]{3}([0-9]{2}(-?[0-9]{4})?)?$","description":"ZIP code, 5 digits or ZIP+4 -- or just the first 3 digits once redacted."},"country":{"type":"string","enum":["US"],"default":"US","description":"US only in v0."}},"required":["city","state"],"additionalProperties":false},"created_at":{"type":"string","format":"date-time"},"events":{"type":"array","items":{"type":"object","properties":{"at":{"type":"string","format":"date-time"},"status":{"type":"string"},"detail":{"type":"string"}},"required":["at","status"],"additionalProperties":false}}},"required":["shipment_id","kind","status","carrier","service","tracking_code","credits_charged_cents","refund_status","from","to","created_at","events"],"additionalProperties":false}}}},"400":{"description":"invalid_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized. Carries WWW-Authenticate: Bearer resource_metadata=\"...\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"forbidden_scope: a write tool called with a read-only key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"provider_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"shipment_id","in":"path","required":true,"schema":{"type":"string","maxLength":64,"minLength":1,"pattern":"^sh_[A-Za-z0-9]+$"}}]}},"/v1/shipments":{"get":{"operationId":"list_shipments","summary":"List shipments","description":"List this account's labels newest first, with a cursor for paging; free and read-only.","x-muse-classification":{"class":"read","label":"Read","side_effects":"None.","cost":"Free","approval":"None: safe to call without asking.","key_scope":"read","idempotent":true},"tags":["ship"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","title":"Shipment","properties":{"shipment_id":{"type":"string","maxLength":64,"description":"Opaque id, \"sh_...\". Use it with get_shipment."},"kind":{"type":"string","enum":["outbound","return"]},"status":{"type":"string","enum":["unknown","pre_transit","in_transit","out_for_delivery","delivered","available_for_pickup","return_to_sender","failure","cancelled","error"],"description":"The carrier's tracking status. pre_transit means the label exists and nothing has been scanned yet."},"carrier":{"type":"string","maxLength":40},"service":{"type":"string","maxLength":80},"tracking_code":{"type":"string","maxLength":64},"label_url":{"type":"string","format":"uri","description":"The printable PDF label. Gone after the retention window."},"qr_code_url":{"type":"string","format":"uri","description":"USPS QR code image. The human shows it at a post office counter and the clerk prints the label."},"tracking_url":{"type":"string","format":"uri","description":"The carrier's public tracking page."},"est_delivery_date":{"type":"string","maxLength":40},"credits_charged_cents":{"type":"integer","minimum":0,"description":"Net credits this label cost: zero once a refund has been confirmed."},"refund_status":{"type":"string","enum":["none","submitted","refunded","rejected"],"description":"none, or after void_label: submitted (waiting on the carrier), refunded (credits are back), rejected (the label was used or too old)."},"from":{"type":"object","title":"StoredAddress","description":"A US postal address as stored. After the 30-day retention window only city, state and the first 3 ZIP digits remain; name, company and street lines are permanently removed.","properties":{"name":{"type":"string","maxLength":40,"minLength":1,"description":"Recipient or sender name, 1-40 characters."},"company":{"type":"string","maxLength":40,"description":"Optional company line, up to 40 characters."},"line1":{"type":"string","maxLength":64,"minLength":1,"description":"Street address, up to 64 characters."},"line2":{"type":"string","maxLength":64,"description":"Apartment, suite, or unit, up to 64 characters."},"city":{"type":"string","maxLength":200,"minLength":1},"state":{"type":"string","maxLength":2,"minLength":2,"pattern":"^[A-Za-z]{2}$","description":"Two-letter US state code."},"zip":{"type":"string","pattern":"^[0-9]{3}([0-9]{2}(-?[0-9]{4})?)?$","description":"ZIP code, 5 digits or ZIP+4 -- or just the first 3 digits once redacted."},"country":{"type":"string","enum":["US"],"default":"US","description":"US only in v0."}},"required":["city","state"],"additionalProperties":false},"to":{"type":"object","title":"StoredAddress","description":"A US postal address as stored. After the 30-day retention window only city, state and the first 3 ZIP digits remain; name, company and street lines are permanently removed.","properties":{"name":{"type":"string","maxLength":40,"minLength":1,"description":"Recipient or sender name, 1-40 characters."},"company":{"type":"string","maxLength":40,"description":"Optional company line, up to 40 characters."},"line1":{"type":"string","maxLength":64,"minLength":1,"description":"Street address, up to 64 characters."},"line2":{"type":"string","maxLength":64,"description":"Apartment, suite, or unit, up to 64 characters."},"city":{"type":"string","maxLength":200,"minLength":1},"state":{"type":"string","maxLength":2,"minLength":2,"pattern":"^[A-Za-z]{2}$","description":"Two-letter US state code."},"zip":{"type":"string","pattern":"^[0-9]{3}([0-9]{2}(-?[0-9]{4})?)?$","description":"ZIP code, 5 digits or ZIP+4 -- or just the first 3 digits once redacted."},"country":{"type":"string","enum":["US"],"default":"US","description":"US only in v0."}},"required":["city","state"],"additionalProperties":false},"created_at":{"type":"string","format":"date-time"}},"required":["shipment_id","kind","status","carrier","service","tracking_code","credits_charged_cents","refund_status","from","to","created_at"],"additionalProperties":false}},"next_cursor":{"type":"string"}},"required":["items"],"additionalProperties":false}}}},"400":{"description":"invalid_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized. Carries WWW-Authenticate: Bearer resource_metadata=\"...\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"forbidden_scope: a write tool called with a read-only key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"provider_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":256,"description":"Opaque cursor from a previous next_cursor."},"description":"Opaque cursor from a previous next_cursor."}]}},"/v1/track":{"get":{"operationId":"track_package","summary":"Track a package","description":"Track any package from any major carrier by tracking number (USPS, UPS, FedEx, DHL and more; carrier optional); free and read-only, with up to 30 new tracking numbers per account per day and unlimited re-checks of ones already looked up.","x-muse-classification":{"class":"read","label":"Read","side_effects":"None.","cost":"Free","approval":"None: safe to call without asking.","key_scope":"read","rate_limit":"30 new tracking numbers a day per account; re-checks are not counted","idempotent":true},"tags":["ship"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","title":"Tracking","properties":{"tracking_code":{"type":"string","maxLength":40},"carrier":{"type":"string","maxLength":40},"status":{"type":"string","enum":["unknown","pre_transit","in_transit","out_for_delivery","delivered","available_for_pickup","return_to_sender","failure","cancelled","error"]},"status_detail":{"type":"string","maxLength":80},"est_delivery_date":{"type":"string","maxLength":40},"public_url":{"type":"string","format":"uri"},"events":{"type":"array","description":"Newest first, at most 10.","items":{"type":"object","properties":{"at":{"type":"string","maxLength":40},"status":{"type":"string","maxLength":40},"message":{"type":"string","maxLength":300},"location":{"type":"string","maxLength":120}},"required":["at","status"],"additionalProperties":false}}},"required":["tracking_code","carrier","status","events"],"additionalProperties":false}}}},"400":{"description":"invalid_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized. Carries WWW-Authenticate: Bearer resource_metadata=\"...\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"forbidden_scope: a write tool called with a read-only key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"provider_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"tracking_code","in":"query","required":true,"schema":{"type":"string","maxLength":40,"minLength":6,"pattern":"^[A-Za-z0-9]+$","description":"Any carrier tracking number, letters and digits only (strip spaces)."},"description":"Any carrier tracking number, letters and digits only (strip spaces)."},{"name":"carrier","in":"query","required":false,"schema":{"type":"string","maxLength":30,"pattern":"^[A-Za-z0-9 ]+$","description":"Optional, e.g. USPS, UPS, FedEx. Leave it out if unsure; the carrier is detected."},"description":"Optional, e.g. USPS, UPS, FedEx. Leave it out if unsure; the carrier is detected."}]}},"/v1/shipments/{shipment_id}/void":{"post":{"operationId":"void_label","summary":"Void a label","description":"Ask the carrier to refund a label that has not been used (nothing scanned yet), with confirm true; CONSEQUENTIAL and irreversible -- the label stops being valid -- and the credits come back only when the carrier confirms the refund, which for USPS takes about 15 days or more. Free. Sensitive write: it requires the human's approval to void that label.","x-muse-classification":{"class":"sensitive_write","label":"Sensitive write","side_effects":"Asks the carrier to refund an unused label; the label stops being valid at once. Credits return only when the carrier confirms (about 15 days or more for USPS). Irreversible.","cost":"Free","approval":"Explicit approval to void that label.","key_scope":"write","idempotent":false},"tags":["ship"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","title":"Shipment","properties":{"shipment_id":{"type":"string","maxLength":64,"description":"Opaque id, \"sh_...\". Use it with get_shipment."},"kind":{"type":"string","enum":["outbound","return"]},"status":{"type":"string","enum":["unknown","pre_transit","in_transit","out_for_delivery","delivered","available_for_pickup","return_to_sender","failure","cancelled","error"],"description":"The carrier's tracking status. pre_transit means the label exists and nothing has been scanned yet."},"carrier":{"type":"string","maxLength":40},"service":{"type":"string","maxLength":80},"tracking_code":{"type":"string","maxLength":64},"label_url":{"type":"string","format":"uri","description":"The printable PDF label. Gone after the retention window."},"qr_code_url":{"type":"string","format":"uri","description":"USPS QR code image. The human shows it at a post office counter and the clerk prints the label."},"tracking_url":{"type":"string","format":"uri","description":"The carrier's public tracking page."},"est_delivery_date":{"type":"string","maxLength":40},"credits_charged_cents":{"type":"integer","minimum":0,"description":"Net credits this label cost: zero once a refund has been confirmed."},"refund_status":{"type":"string","enum":["none","submitted","refunded","rejected"],"description":"none, or after void_label: submitted (waiting on the carrier), refunded (credits are back), rejected (the label was used or too old)."},"from":{"type":"object","title":"StoredAddress","description":"A US postal address as stored. After the 30-day retention window only city, state and the first 3 ZIP digits remain; name, company and street lines are permanently removed.","properties":{"name":{"type":"string","maxLength":40,"minLength":1,"description":"Recipient or sender name, 1-40 characters."},"company":{"type":"string","maxLength":40,"description":"Optional company line, up to 40 characters."},"line1":{"type":"string","maxLength":64,"minLength":1,"description":"Street address, up to 64 characters."},"line2":{"type":"string","maxLength":64,"description":"Apartment, suite, or unit, up to 64 characters."},"city":{"type":"string","maxLength":200,"minLength":1},"state":{"type":"string","maxLength":2,"minLength":2,"pattern":"^[A-Za-z]{2}$","description":"Two-letter US state code."},"zip":{"type":"string","pattern":"^[0-9]{3}([0-9]{2}(-?[0-9]{4})?)?$","description":"ZIP code, 5 digits or ZIP+4 -- or just the first 3 digits once redacted."},"country":{"type":"string","enum":["US"],"default":"US","description":"US only in v0."}},"required":["city","state"],"additionalProperties":false},"to":{"type":"object","title":"StoredAddress","description":"A US postal address as stored. After the 30-day retention window only city, state and the first 3 ZIP digits remain; name, company and street lines are permanently removed.","properties":{"name":{"type":"string","maxLength":40,"minLength":1,"description":"Recipient or sender name, 1-40 characters."},"company":{"type":"string","maxLength":40,"description":"Optional company line, up to 40 characters."},"line1":{"type":"string","maxLength":64,"minLength":1,"description":"Street address, up to 64 characters."},"line2":{"type":"string","maxLength":64,"description":"Apartment, suite, or unit, up to 64 characters."},"city":{"type":"string","maxLength":200,"minLength":1},"state":{"type":"string","maxLength":2,"minLength":2,"pattern":"^[A-Za-z]{2}$","description":"Two-letter US state code."},"zip":{"type":"string","pattern":"^[0-9]{3}([0-9]{2}(-?[0-9]{4})?)?$","description":"ZIP code, 5 digits or ZIP+4 -- or just the first 3 digits once redacted."},"country":{"type":"string","enum":["US"],"default":"US","description":"US only in v0."}},"required":["city","state"],"additionalProperties":false},"created_at":{"type":"string","format":"date-time"}},"required":["shipment_id","kind","status","carrier","service","tracking_code","credits_charged_cents","refund_status","from","to","created_at"],"additionalProperties":false}}}},"400":{"description":"invalid_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized. Carries WWW-Authenticate: Bearer resource_metadata=\"...\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"forbidden_scope: a write tool called with a read-only key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"provider_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"shipment_id","in":"path","required":true,"schema":{"type":"string","maxLength":64,"minLength":1,"pattern":"^sh_[A-Za-z0-9]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shipment_id":{"type":"string","maxLength":64,"minLength":1,"pattern":"^sh_[A-Za-z0-9]+$"},"confirm":{"type":"boolean","const":true,"description":"Must be true. Set it only after the human approved this exact action and price."}},"required":["shipment_id","confirm"],"additionalProperties":false}}}}}},"/v1/pickups/options":{"post":{"operationId":"get_pickup_options","summary":"Get pickup options","description":"See whether a carrier can collect a bought label's package from its \"from\" address in a time window, and what it costs (a USPS pickup is free); free and nothing is booked -- schedule_pickup does that.","x-muse-classification":{"class":"read","label":"Read","side_effects":"None.","cost":"Free","approval":"None: safe to call without asking.","key_scope":"read","idempotent":false},"tags":["ship"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"pickup_id":{"type":"string","maxLength":64,"description":"Opaque id, \"pu_...\". Pass it to schedule_pickup."},"options":{"type":"array","items":{"type":"object","properties":{"carrier":{"type":"string","maxLength":40},"service":{"type":"string","maxLength":80,"description":"Pass this to schedule_pickup."},"price_cents":{"type":"integer","minimum":0,"description":"Zero for a free USPS pickup."}},"required":["carrier","service","price_cents"],"additionalProperties":false}},"expires_at":{"type":"string","format":"date-time"}},"required":["pickup_id","options","expires_at"],"additionalProperties":false}}}},"400":{"description":"invalid_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized. Carries WWW-Authenticate: Bearer resource_metadata=\"...\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"forbidden_scope: a write tool called with a read-only key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"provider_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"shipment_id":{"type":"string","maxLength":64,"minLength":1,"pattern":"^sh_[A-Za-z0-9]+$","description":"The label to be picked up. The pickup is at that label's \"from\" address."},"earliest":{"type":"string","maxLength":40,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}(:[0-9]{2})?(Z|[+-][0-9]{2}:[0-9]{2})$","description":"Start of the pickup window, ISO with offset, e.g. \"2026-09-24T09:00:00-05:00\"."},"latest":{"type":"string","maxLength":40,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}(:[0-9]{2})?(Z|[+-][0-9]{2}:[0-9]{2})$","description":"End of the window, same format. USPS picks up on the next delivery day inside it."},"instructions":{"type":"string","maxLength":200,"description":"Optional, for the carrier: where the package will be, e.g. \"on the front porch\"."}},"required":["shipment_id","earliest","latest"],"additionalProperties":false}}}}}},"/v1/pickups":{"post":{"operationId":"schedule_pickup","summary":"Schedule a pickup","description":"Book the carrier pickup for one pickup_id and service, with confirm true; CONSEQUENTIAL -- a driver is sent to the address -- and charged only if that option's price_cents is above zero (USPS pickups are free). Sensitive write: it requires the human's approval of the window, address and price. Returns the carrier's confirmation number.","x-muse-classification":{"class":"sensitive_write","label":"Sensitive write","side_effects":"Books a carrier pickup: a driver is sent to the address. Debits credits only if the option has a price.","cost":"The option's price_cents; USPS pickups are free","approval":"Explicit approval of the pickup window, address and price.","key_scope":"write","idempotent":false},"tags":["ship"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","title":"Pickup","properties":{"pickup_id":{"type":"string","maxLength":64},"shipment_id":{"type":"string","maxLength":64},"status":{"type":"string","enum":["quoted","scheduled","cancelled"]},"carrier":{"type":"string","maxLength":40},"service":{"type":"string","maxLength":80},"confirmation":{"type":"string","maxLength":80,"description":"The carrier's confirmation number. Give it to the human."},"earliest":{"type":"string","maxLength":40},"latest":{"type":"string","maxLength":40},"credits_charged_cents":{"type":"integer","minimum":0},"balance_cents":{"type":"integer","description":"General credit left."}},"required":["pickup_id","shipment_id","status","earliest","latest","credits_charged_cents","balance_cents"],"additionalProperties":false}}}},"400":{"description":"invalid_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized. Carries WWW-Authenticate: Bearer resource_metadata=\"...\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_credits, with required_cents, balance_cents, topup_url and packs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"forbidden_scope: a write tool called with a read-only key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"idempotency_conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"provider_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pickup_id":{"type":"string","maxLength":64,"minLength":1,"pattern":"^pu_[A-Za-z0-9]+$"},"service":{"type":"string","maxLength":80,"minLength":1,"description":"One service from get_pickup_options."},"confirm":{"type":"boolean","const":true,"description":"Must be true. Set it only after the human approved this exact action and price."},"idempotency_key":{"type":"string","maxLength":128,"description":"Use one key per human request. Replays within 24 hours return the original result instead of buying twice."}},"required":["pickup_id","service","confirm"],"additionalProperties":false}}}}}},"/v1/pickups/{pickup_id}/cancel":{"post":{"operationId":"cancel_pickup","summary":"Cancel a pickup","description":"Cancel a scheduled pickup with confirm true, and refund it in full if it was paid; irreversible, and the driver will not come. Free. Sensitive write: it requires the human's approval to cancel.","x-muse-classification":{"class":"sensitive_write","label":"Sensitive write","side_effects":"Cancels the carrier pickup and refunds it in full if it was paid. Irreversible.","cost":"Free","approval":"Explicit approval to cancel that pickup.","key_scope":"write","idempotent":true},"tags":["ship"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","title":"Pickup","properties":{"pickup_id":{"type":"string","maxLength":64},"shipment_id":{"type":"string","maxLength":64},"status":{"type":"string","enum":["quoted","scheduled","cancelled"]},"carrier":{"type":"string","maxLength":40},"service":{"type":"string","maxLength":80},"confirmation":{"type":"string","maxLength":80,"description":"The carrier's confirmation number. Give it to the human."},"earliest":{"type":"string","maxLength":40},"latest":{"type":"string","maxLength":40},"credits_charged_cents":{"type":"integer","minimum":0},"balance_cents":{"type":"integer","description":"General credit left."}},"required":["pickup_id","shipment_id","status","earliest","latest","credits_charged_cents","balance_cents"],"additionalProperties":false}}}},"400":{"description":"invalid_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized. Carries WWW-Authenticate: Bearer resource_metadata=\"...\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"forbidden_scope: a write tool called with a read-only key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"provider_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"pickup_id","in":"path","required":true,"schema":{"type":"string","maxLength":64,"minLength":1,"pattern":"^pu_[A-Za-z0-9]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pickup_id":{"type":"string","maxLength":64,"minLength":1,"pattern":"^pu_[A-Za-z0-9]+$"},"confirm":{"type":"boolean","const":true,"description":"Must be true. Set it only after the human approved this exact action and price."}},"required":["pickup_id","confirm"],"additionalProperties":false}}}}}},"/v1/balance":{"get":{"operationId":"get_balance","summary":"Get balance","description":"Report the prepaid credit balance in cents (general credit, which pays for labels), where to add more, and the credit packs on offer; free, read-only, and not consequential.","x-muse-classification":{"class":"read","label":"Read","side_effects":"None.","cost":"Free","approval":"None: safe to call without asking.","key_scope":"read","idempotent":true},"tags":["ship"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"balance_cents":{"type":"integer"},"currency":{"type":"string","enum":["usd"]},"topup_url":{"type":"string","format":"uri"},"packs":{"type":"array","description":"Everything that can be bought, cheapest first. The first entry is a one-off single letter; every pack after it credits more than it costs, so quote both numbers to the human.","items":{"type":"object","title":"CreditPack","description":"A buyable amount: what it costs, what it credits, and the bonus in free letters. The cheapest is the one-off single letter, which has no bonus.","properties":{"pay_cents":{"type":"integer","description":"What the human pays, in cents."},"credits_cents":{"type":"integer","description":"What lands in the balance, in cents. Larger than pay_cents for a pack; equal for the one-off letter."},"free_letters":{"type":"integer","description":"Whole one-page letters the bonus alone pays for. Say it to the human as \"three free letters\". Zero for the one-off letter."},"label":{"type":"string","description":"What to call it to the human: \"One letter\" for the one-off purchase, \"$25 pack\" for a pack."}},"required":["pay_cents","credits_cents","free_letters","label"],"additionalProperties":false}}},"required":["balance_cents","currency","topup_url","packs"],"additionalProperties":false}}}},"400":{"description":"invalid_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized. Carries WWW-Authenticate: Bearer resource_metadata=\"...\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"forbidden_scope: a write tool called with a read-only key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"provider_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/topups":{"post":{"operationId":"create_topup_link","summary":"Create top-up link","description":"Create a Stripe Checkout link to buy one of the credit packs (amount_cents), and report every pack with what it credits. Creates a Stripe Checkout session but charges nothing: money moves only if the human opens the link and pays, and the credit lands when Stripe confirms the payment. Free.","x-muse-classification":{"class":"write","label":"Write","side_effects":"Creates a Stripe Checkout session. No money moves and no credit is added unless the human opens the link and pays.","cost":"Free to call; the human pays only the amount they choose at checkout.","approval":"None to create the link; the human approves the payment itself on Stripe's checkout page.","key_scope":"read","idempotent":false},"tags":["ship"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"checkout_url":{"type":"string","format":"uri"},"expires_at":{"type":"string","format":"date-time"},"packs":{"type":"array","description":"Everything that can be bought, cheapest first. The first entry is a one-off single letter; every pack after it credits more than it costs, so quote both numbers to the human.","items":{"type":"object","title":"CreditPack","description":"A buyable amount: what it costs, what it credits, and the bonus in free letters. The cheapest is the one-off single letter, which has no bonus.","properties":{"pay_cents":{"type":"integer","description":"What the human pays, in cents."},"credits_cents":{"type":"integer","description":"What lands in the balance, in cents. Larger than pay_cents for a pack; equal for the one-off letter."},"free_letters":{"type":"integer","description":"Whole one-page letters the bonus alone pays for. Say it to the human as \"three free letters\". Zero for the one-off letter."},"label":{"type":"string","description":"What to call it to the human: \"One letter\" for the one-off purchase, \"$25 pack\" for a pack."}},"required":["pay_cents","credits_cents","free_letters","label"],"additionalProperties":false}}},"required":["checkout_url","expires_at","packs"],"additionalProperties":false}}}},"400":{"description":"invalid_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized. Carries WWW-Authenticate: Bearer resource_metadata=\"...\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"forbidden_scope: a write tool called with a read-only key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"provider_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount_cents":{"type":"integer","enum":[249,1000,2500,5000],"description":"What to charge, in cents: the one-off single letter or one of the credit packs, as its pay_cents. A pack credits more than it costs; see packs."}},"required":["amount_cents"],"additionalProperties":false}}}}}},"/v1/me":{"delete":{"operationId":"delete_my_data","summary":"Delete my data","description":"Erase the personal data this account holds: every stored recipient and sender address, fax number, booking customer and restaurant-table diner is redacted, every API key on the account is revoked, and the account is closed, while the prepaid credit ledger is kept so the balance and charges stay provable. CONSEQUENTIAL and IRREVERSIBLE: there is no undo and support cannot restore the data. Free. Sensitive write: it requires that the human has explicitly confirmed they want their data deleted. A copy of the revoked key saved in the agent's own credential store stays there until the human removes it; this call cannot reach into the agent to delete it.","x-muse-classification":{"class":"sensitive_write","label":"Sensitive write","side_effects":"Redacts every personal record on the account, revokes every API key and closes the account; the credit ledger is kept. Irreversible.","cost":"Free","approval":"The human explicitly confirms, in words, that they want all their data deleted.","key_scope":"write","idempotent":true},"tags":["ship"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","title":"DeleteMyDataResult","properties":{"deleted":{"const":true,"description":"Always true; a failure is an error envelope instead."},"redacted":{"type":"object","title":"RedactedCounts","description":"How many records of each kind this request scrubbed.","properties":{"mail":{"type":"integer","minimum":0},"faxes":{"type":"integer","minimum":0},"bookings":{"type":"integer","minimum":0},"table_requests":{"type":"integer","minimum":0},"shipments":{"type":"integer","minimum":0},"print_orders":{"type":"integer","minimum":0},"cards":{"type":"integer","minimum":0},"courier_deliveries":{"type":"integer","minimum":0},"sign_envelopes":{"type":"integer","minimum":0},"x402_limit_requests":{"type":"integer","minimum":0}},"required":["mail","faxes","bookings"],"additionalProperties":false}},"required":["deleted","redacted"],"additionalProperties":false}}}},"400":{"description":"invalid_request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"unauthorized. Carries WWW-Authenticate: Bearer resource_metadata=\"...\"","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"forbidden_scope: a write tool called with a read-only key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"not_found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"rate_limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"provider_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Store the key in Muse's Secure Credentials Store as NOERRANDS_API_KEY. A 401 carries WWW-Authenticate: Bearer resource_metadata=\"https://api.noerrands.com/.well-known/oauth-protected-resource/c/ship/mcp\"."}},"schemas":{"Error":{"type":"object","title":"Error","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_request","unauthorized","insufficient_credits","forbidden_scope","not_found","idempotency_conflict","conflict","rate_limited","provider_error"]},"message":{"type":"string"},"field":{"type":"string"},"required_cents":{"type":"integer"},"balance_cents":{"type":"integer"},"topup_url":{"type":"string"},"packs":{"type":"array","description":"Everything that can be bought, cheapest first. The first entry is a one-off single letter; every pack after it credits more than it costs, so quote both numbers to the human.","items":{"type":"object","title":"CreditPack","description":"A buyable amount: what it costs, what it credits, and the bonus in free letters. The cheapest is the one-off single letter, which has no bonus.","properties":{"pay_cents":{"type":"integer","description":"What the human pays, in cents."},"credits_cents":{"type":"integer","description":"What lands in the balance, in cents. Larger than pay_cents for a pack; equal for the one-off letter."},"free_letters":{"type":"integer","description":"Whole one-page letters the bonus alone pays for. Say it to the human as \"three free letters\". Zero for the one-off letter."},"label":{"type":"string","description":"What to call it to the human: \"One letter\" for the one-off purchase, \"$25 pack\" for a pack."}},"required":["pay_cents","credits_cents","free_letters","label"],"additionalProperties":false}},"fax_balance_cents":{"type":"integer"},"fax_bundles":{"type":"array","description":"Fax bundles, cheapest first. Prepaid credit that can only be spent on faxes, which is why each one credits far more than it costs. General credit packs pay for faxes too; fax credit does not pay for mail.","items":{"type":"object","title":"FaxBundle","description":"A buyable fax bundle: what it costs, what it credits, and how many one-page faxes that covers. These credits pay for faxes only.","properties":{"label":{"type":"string","description":"What to call it to the human: \"$25 fax bundle\"."},"pay_cents":{"type":"integer","description":"What the human pays, in cents."},"credits_cents":{"type":"integer","description":"What lands in the fax-only balance, in cents. Always larger than pay_cents."},"one_page_faxes":{"type":"integer","description":"Whole one-page faxes the bundle covers. Say this number to the human."}},"required":["label","pay_cents","credits_cents","one_page_faxes"],"additionalProperties":false}},"x402":{"type":"object","properties":{"topup_url":{"type":"string"},"amount_cents":{"type":"integer"},"networks":{"type":"array","items":{"type":"string"}},"asset":{"type":"string","enum":["USDC"]}},"required":["topup_url","amount_cents","networks","asset"]},"retry_after_seconds":{"type":"integer"}},"required":["code","message"]}},"required":["error"]}}},"x-root-endpoints":{"description":"Endpoints on the Worker root rather than the connector base.","paths":{"https://api.noerrands.com/v1/keys":{"post":{"operationId":"create_key","summary":"Issue an API key","description":"Create an account and API key that works for every No Errands connector. No auth. Rate limited to 5 per IP per hour. The key is shown exactly once.","responses":{"201":{"description":"Key created.","content":{"application/json":{"schema":{"type":"object"}}}}}}},"https://api.noerrands.com/.well-known/oauth-protected-resource/c/ship/mcp":{"get":{"operationId":"ship_protected_resource_metadata","summary":"RFC 9728 protected resource metadata","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}}