{"openapi":"3.1.0","info":{"title":"No Errands Cards API","version":"0.1.0","summary":"Mail a real greeting card, handwritten with a real pen or printed, from an agent.","description":"No Errands mails real greeting cards to US addresses. Every response is data, 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 general credit in integer cents. A handwritten card costs 899\ncredits and a printed card 399. `send_card` returns 402 `insufficient_credits`\nwith `required_cents`, `balance_cents`, `topup_url` and `packs` when the balance is short.\n\nFlow: `list_card_designs` -> `preview_card` (free; returns a single-use `quote_id`, valid\n24 hours) -> `send_card` with `quote_id` and `confirm: true` (charged). The quote is the\nidempotency key: repeating `send_card` returns the original card and never charges twice.\n\nScheduling: `preview_card` takes `send_on` (the dispatch date) or `arrive_by` (we dispatch\nearly enough). A scheduled card is paid when confirmed and can be cancelled for a full\nrefund until its dispatch date. A printed card is an open postcard.\n\nAn MCP streamable-HTTP server exposing the same tools is at https://api.noerrands.com/c/cards/mcp.","contact":{"email":"support@noerrands.com","url":"https://noerrands.com/docs"},"termsOfService":"https://noerrands.com/connectors/cards/terms"},"servers":[{"url":"https://api.noerrands.com/c/cards","description":"No Errands cards connector"}],"tags":[{"name":"cards","description":"Greeting cards"}],"externalDocs":{"description":"Cards connector brief","url":"https://noerrands.com/connectors/cards/muse.md"},"paths":{"/v1/designs":{"get":{"operationId":"list_card_designs","summary":"List card designs","description":"List greeting card designs, optionally by occasion (birthday, thank_you, sympathy, holiday, congratulations, anniversary, get_well, thinking_of_you, other) and tier -- handwritten (899 credits: a folded card written with a real pen, in a stamped envelope) or printed (399 credits: a 6x9 postcard-style card whose message anyone handling it can read); 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":["cards"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"designs":{"type":"array","items":{"type":"object","title":"CardDesign","properties":{"design_id":{"type":"string","maxLength":64,"description":"Pass to preview_card. hw_... is handwritten, pr_... is printed."},"name":{"type":"string","maxLength":120},"tier":{"type":"string","enum":["handwritten","printed"],"description":"handwritten: a folded card written with a real pen, in a stamped envelope. printed: a 6x9 postcard-style card, message printed on the back where anyone handling it can read it."},"occasion":{"type":"string","enum":["birthday","thank_you","sympathy","holiday","congratulations","anniversary","get_well","thinking_of_you","other"],"description":"birthday, thank_you, sympathy, holiday, congratulations, anniversary, get_well, thinking_of_you or other."},"price_cents":{"type":"integer","minimum":0,"description":"What a card in this design costs, in credits."},"image_url":{"type":"string","maxLength":2048,"format":"uri","description":"Cover image hosted by the provider, when it has one."},"preview_url":{"type":"string","maxLength":2048,"format":"uri","description":"A page showing the front of a printed design."}},"required":["design_id","name","tier","occasion","price_cents"],"additionalProperties":false},"maxItems":40}},"required":["designs"],"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":"occasion","in":"query","required":false,"schema":{"type":"string","enum":["birthday","thank_you","sympathy","holiday","congratulations","anniversary","get_well","thinking_of_you","other"],"description":"birthday, thank_you, sympathy, holiday, congratulations, anniversary, get_well, thinking_of_you or other."},"description":"birthday, thank_you, sympathy, holiday, congratulations, anniversary, get_well, thinking_of_you or other."},{"name":"tier","in":"query","required":false,"schema":{"type":"string","enum":["handwritten","printed"],"description":"handwritten: a folded card written with a real pen, in a stamped envelope. printed: a 6x9 postcard-style card, message printed on the back where anyone handling it can read it."},"description":"handwritten: a folded card written with a real pen, in a stamped envelope. printed: a 6x9 postcard-style card, message printed on the back where anyone handling it can read it."}]}},"/v1/styles":{"get":{"operationId":"list_handwriting_styles","summary":"List handwriting styles","description":"List the handwriting styles a handwritten card can be written in, with sample images where the provider has them; free, read-only, and not consequential. Printed cards are typeset and take no style.","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":["cards"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"styles":{"type":"array","items":{"type":"object","title":"HandwritingStyle","properties":{"style_id":{"type":"string","maxLength":80,"description":"Pass as handwriting_style to preview_card."},"name":{"type":"string","maxLength":80},"sample_url":{"type":"string","maxLength":2048,"format":"uri"}},"required":["style_id","name"],"additionalProperties":false}}},"required":["styles"],"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/quotes":{"post":{"operationId":"preview_card","summary":"Preview a card","description":"Price one card and hold a single-use quote for 24 hours: the design, message, sign-off, style, recipient, return address, and either send_on (dispatch date) or arrive_by (we work the dispatch date out); returns quote_id, price_cents, dispatch_on and estimated_arrival. Free and not consequential -- nothing is charged or mailed -- and the only way to get the quote_id send_card needs.","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":["cards"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"quote_id":{"type":"string","maxLength":64,"description":"Single-use, valid 24 hours. Pass to send_card with confirm: true."},"tier":{"type":"string","enum":["handwritten","printed"],"description":"handwritten: a folded card written with a real pen, in a stamped envelope. printed: a 6x9 postcard-style card, message printed on the back where anyone handling it can read it."},"design":{"type":"object","title":"CardDesign","properties":{"design_id":{"type":"string","maxLength":64,"description":"Pass to preview_card. hw_... is handwritten, pr_... is printed."},"name":{"type":"string","maxLength":120},"tier":{"type":"string","enum":["handwritten","printed"],"description":"handwritten: a folded card written with a real pen, in a stamped envelope. printed: a 6x9 postcard-style card, message printed on the back where anyone handling it can read it."},"occasion":{"type":"string","enum":["birthday","thank_you","sympathy","holiday","congratulations","anniversary","get_well","thinking_of_you","other"],"description":"birthday, thank_you, sympathy, holiday, congratulations, anniversary, get_well, thinking_of_you or other."},"price_cents":{"type":"integer","minimum":0,"description":"What a card in this design costs, in credits."},"image_url":{"type":"string","maxLength":2048,"format":"uri","description":"Cover image hosted by the provider, when it has one."},"preview_url":{"type":"string","maxLength":2048,"format":"uri","description":"A page showing the front of a printed design."}},"required":["design_id","name","tier","occasion","price_cents"],"additionalProperties":false},"handwriting_style":{"type":"string","maxLength":80},"price_cents":{"type":"integer","minimum":0},"balance_cents":{"type":"integer","description":"General credit available now."},"affordable":{"type":"boolean","description":"Whether the balance covers price_cents now."},"dispatch_on":{"type":"string","maxLength":10,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","format":"date","description":"The day the card goes to the provider."},"estimated_arrival":{"type":"object","title":"EstimatedArrival","properties":{"earliest":{"type":"string","maxLength":10,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","format":"date","description":"Earliest likely delivery date."},"latest":{"type":"string","maxLength":10,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","format":"date","description":"Latest likely delivery date. USPS does not guarantee it."}},"required":["earliest","latest"],"additionalProperties":false},"expires_at":{"type":"string","format":"date-time"},"preview_url":{"type":"string","maxLength":2048,"format":"uri"},"notes":{"type":"array","items":{"type":"string"}}},"required":["quote_id","tier","design","price_cents","balance_cents","affordable","dispatch_on","estimated_arrival","expires_at","notes"],"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":{"design_id":{"type":"string","maxLength":64,"minLength":4,"description":"From list_card_designs. Fixes the tier."},"message":{"type":"string","maxLength":500,"minLength":1,"description":"The message inside the card. Up to 320 characters handwritten, 500 printed. Use \\n for line breaks."},"signoff":{"type":"string","maxLength":60,"description":"The closing line, e.g. \"Love, Sam\"."},"handwriting_style":{"type":"string","maxLength":80,"description":"Handwritten tier only: a style_id from list_handwriting_styles. Defaults to the first style."},"to":{"type":"object","title":"AddressWithName","description":"Who receives the card. US only.","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."}},"required":["name","line1","city","state","zip"],"additionalProperties":false},"from":{"type":"object","title":"AddressWithName","description":"The sender and return address. US only.","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."}},"required":["name","line1","city","state","zip"],"additionalProperties":false},"send_on":{"type":"string","maxLength":10,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","format":"date","description":"Dispatch date, YYYY-MM-DD. Give this or arrive_by, not both. Omit both to send today."},"arrive_by":{"type":"string","maxLength":10,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","format":"date","description":"Date the card should arrive by, YYYY-MM-DD. The dispatch date is worked out from it."}},"required":["design_id","message","to","from"],"additionalProperties":false}}}}}},"/v1/cards":{"post":{"operationId":"send_card","summary":"Send a card","description":"Mail the card a quote describes: CONSEQUENTIAL and charged (899 credits handwritten, 399 printed) -- a real card goes to a real person. Takes the quote_id with confirm: true. Sensitive write: it requires the human's approval of the preview (design, full message, recipient and address, tier, price, dispatch date). The same quote_id never sends or charges twice; a card scheduled for a later day can be cancelled for a full refund until it leaves.","x-muse-classification":{"class":"sensitive_write","label":"Sensitive write","side_effects":"Has a real card made and mailed to the recipient and debits credits.","cost":"899 credits handwritten, 399 printed","approval":"Explicit approval of the design, full message, recipient and address, tier, price and dispatch date.","key_scope":"write","idempotent":true},"tags":["cards"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"card_id":{"type":"string","maxLength":64,"description":"Opaque id, \"cd_...\". Use it with get_card and cancel_card."},"status":{"type":"string","enum":["scheduled","submitted","in_production","mailed","delivered","returned","cancelled","failed"],"description":"scheduled (held until dispatch_on) -> submitted -> in_production -> mailed -> delivered; or returned, cancelled, failed."},"tier":{"type":"string","enum":["handwritten","printed"],"description":"handwritten: a folded card written with a real pen, in a stamped envelope. printed: a 6x9 postcard-style card, message printed on the back where anyone handling it can read it."},"dispatch_on":{"type":"string","maxLength":10,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","format":"date","description":"The day the card goes to the provider."},"estimated_arrival":{"type":"object","title":"EstimatedArrival","properties":{"earliest":{"type":"string","maxLength":10,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","format":"date","description":"Earliest likely delivery date."},"latest":{"type":"string","maxLength":10,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","format":"date","description":"Latest likely delivery date. USPS does not guarantee it."}},"required":["earliest","latest"],"additionalProperties":false},"credits_charged_cents":{"type":"integer","minimum":0},"balance_cents":{"type":"integer","description":"General credit left."}},"required":["card_id","status","tier","dispatch_on","estimated_arrival","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 and topup_url.","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: the same quote is being sent right now.","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":4,"description":"From preview_card. Repeating it never charges twice."},"confirm":{"type":"boolean","enum":[true],"description":"Must be true: the human has seen the preview and approved sending and paying for it."}},"required":["quote_id","confirm"],"additionalProperties":false}}}}},"get":{"operationId":"list_cards","summary":"List cards","description":"List this account's cards newest first, with a cursor for paging; 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":["cards"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","title":"CardRecord","properties":{"card_id":{"type":"string","maxLength":64},"status":{"type":"string","enum":["scheduled","submitted","in_production","mailed","delivered","returned","cancelled","failed"],"description":"scheduled (held until dispatch_on) -> submitted -> in_production -> mailed -> delivered; or returned, cancelled, failed."},"tier":{"type":"string","enum":["handwritten","printed"],"description":"handwritten: a folded card written with a real pen, in a stamped envelope. printed: a 6x9 postcard-style card, message printed on the back where anyone handling it can read it."},"design_id":{"type":"string","maxLength":64},"design_name":{"type":"string","maxLength":120},"occasion":{"type":"string","enum":["birthday","thank_you","sympathy","holiday","congratulations","anniversary","get_well","thinking_of_you","other"],"description":"birthday, thank_you, sympathy, holiday, congratulations, anniversary, get_well, thinking_of_you or other."},"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},"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},"message":{"type":"string","maxLength":500,"description":"Absent once the 30-day retention window after mailing has closed."},"signoff":{"type":"string","maxLength":60},"handwriting_style":{"type":"string","maxLength":80},"dispatch_on":{"type":"string","maxLength":10,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","format":"date","description":"The day the card goes (or went) to the provider."},"estimated_arrival":{"type":"object","title":"EstimatedArrival","properties":{"earliest":{"type":"string","maxLength":10,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","format":"date","description":"Earliest likely delivery date."},"latest":{"type":"string","maxLength":10,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","format":"date","description":"Latest likely delivery date. USPS does not guarantee it."}},"required":["earliest","latest"],"additionalProperties":false},"credits_charged_cents":{"type":"integer","minimum":0,"description":"Net of any refund."},"created_at":{"type":"string","format":"date-time"},"mailed_at":{"type":"string","format":"date-time"}},"required":["card_id","status","tier","design_id","design_name","occasion","to","from","dispatch_on","estimated_arrival","credits_charged_cents","created_at"],"additionalProperties":false}},"next_cursor":{"type":"string","maxLength":200}},"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":200,"description":"next_cursor from the previous page."},"description":"next_cursor from the previous page."}]}},"/v1/cards/{card_id}":{"get":{"operationId":"get_card","summary":"Get a card","description":"Look up one card by card_id with its status, dispatch date, estimated arrival and history, refreshed from the provider. Free. If the provider failed or cancelled the card, this call refunds its full charge to the balance, once.","x-muse-classification":{"class":"write","label":"Write","side_effects":"Refreshes the stored status from the provider, and refunds the full charge, once, for a card the provider failed or cancelled.","cost":"Free","approval":"None: the only ledger change is a refund in the human's favour.","key_scope":"read","idempotent":true},"tags":["cards"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","title":"CardWithEvents","properties":{"card_id":{"type":"string","maxLength":64},"status":{"type":"string","enum":["scheduled","submitted","in_production","mailed","delivered","returned","cancelled","failed"],"description":"scheduled (held until dispatch_on) -> submitted -> in_production -> mailed -> delivered; or returned, cancelled, failed."},"tier":{"type":"string","enum":["handwritten","printed"],"description":"handwritten: a folded card written with a real pen, in a stamped envelope. printed: a 6x9 postcard-style card, message printed on the back where anyone handling it can read it."},"design_id":{"type":"string","maxLength":64},"design_name":{"type":"string","maxLength":120},"occasion":{"type":"string","enum":["birthday","thank_you","sympathy","holiday","congratulations","anniversary","get_well","thinking_of_you","other"],"description":"birthday, thank_you, sympathy, holiday, congratulations, anniversary, get_well, thinking_of_you or other."},"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},"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},"message":{"type":"string","maxLength":500,"description":"Absent once the 30-day retention window after mailing has closed."},"signoff":{"type":"string","maxLength":60},"handwriting_style":{"type":"string","maxLength":80},"dispatch_on":{"type":"string","maxLength":10,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","format":"date","description":"The day the card goes (or went) to the provider."},"estimated_arrival":{"type":"object","title":"EstimatedArrival","properties":{"earliest":{"type":"string","maxLength":10,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","format":"date","description":"Earliest likely delivery date."},"latest":{"type":"string","maxLength":10,"pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}$","format":"date","description":"Latest likely delivery date. USPS does not guarantee it."}},"required":["earliest","latest"],"additionalProperties":false},"credits_charged_cents":{"type":"integer","minimum":0,"description":"Net of any refund."},"created_at":{"type":"string","format":"date-time"},"mailed_at":{"type":"string","format":"date-time"},"events":{"type":"array","items":{"type":"object","properties":{"at":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["scheduled","submitted","in_production","mailed","delivered","returned","cancelled","failed"],"description":"scheduled (held until dispatch_on) -> submitted -> in_production -> mailed -> delivered; or returned, cancelled, failed."},"detail":{"type":"string"}},"required":["at","status"],"additionalProperties":false}}},"required":["card_id","status","tier","design_id","design_name","occasion","to","from","dispatch_on","estimated_arrival","credits_charged_cents","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":"card_id","in":"path","required":true,"schema":{"type":"string","maxLength":64,"minLength":4,"description":"From send_card or list_cards."},"description":"From send_card or list_cards."}]}},"/v1/cards/{card_id}/cancel":{"post":{"operationId":"cancel_card","summary":"Cancel a card","description":"Cancel a card and refund it in full: always possible while it is scheduled, and possible after dispatch only while the provider has not started on it; irreversible, and the card will not be mailed. Free. Sensitive write: it requires the human's approval to cancel. A card that can no longer be stopped returns 400 naming its status.","x-muse-classification":{"class":"sensitive_write","label":"Sensitive write","side_effects":"Stops the card from being mailed and refunds it in full. Irreversible.","cost":"Free","approval":"Explicit approval to cancel that card.","key_scope":"write","idempotent":true},"tags":["cards"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object","properties":{"card_id":{"type":"string","maxLength":64},"status":{"const":"cancelled"},"refunded_cents":{"type":"integer","minimum":0},"balance_cents":{"type":"integer"}},"required":["card_id","status","refunded_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":"card_id","in":"path","required":true,"schema":{"type":"string","maxLength":64,"minLength":4}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"card_id":{"type":"string","maxLength":64,"minLength":4}},"required":["card_id"],"additionalProperties":false}}}}}},"/v1/balance":{"get":{"operationId":"get_balance","summary":"Get balance","description":"Report the prepaid general credit balance in cents that pays for cards (and for mail, fax and tables), plus 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":["cards"],"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 credit (amount_cents: the one-off single letter or a credit pack, which credits more than it costs). 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":["cards"],"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":["cards"],"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/cards/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/cards/mcp":{"get":{"operationId":"cards_protected_resource_metadata","summary":"RFC 9728 protected resource metadata","responses":{"200":{"description":"Success.","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}}