API documentation

No Errands gives an agent eight real-world abilities in the United States: print and mail letters and postcards, send faxes, book appointments with local businesses, ask a restaurant for a table by telephone, buy shipping labels, print and post photos, mail greeting cards, and get a PDF signed electronically. This page is the human version of the eight connector briefs that agents read. All of them describe the same v0 contracts.

If you only want to use this from Muse, you do not need this page. Start at Get your key instead.

The eight connectors

They share one account, one API key, one credit balance, one error envelope and one authentication scheme. REST and MCP take the same request bodies and return the same response bodies, so pick whichever your client speaks.

Authentication

Every call carries your key as a bearer token:

Authorization: Bearer ne_live_your_key_here

Keys look like ne_live_ or ne_test_ followed by 32 characters. We store only a SHA-256 hash and the first 12 characters, so we cannot tell you your key if you lose it. Create a new one instead.

A key has one of two scopes:

If the key is missing or wrong you get 401 plus a WWW-Authenticate: Bearer resource_metadata="..." header pointing at that connector's RFC 9728 document.

Getting a key

POST https://api.noerrands.com/v1/keys - no authentication, limited to 5 requests per hour per IP.

Request: { "email": "you@example.com", "scope": "read,write" }

Response 201:

{
  "account_id": "acc_...",
  "api_key": "ne_live_...",
  "scope": "read,write",
  "balance_cents": 0,
  "topup_url": "https://..."
}

The key page calls this endpoint for you. One key works for all eight connectors. Email addresses are not verified in v0; treat the key, not the email, as the account identity.

Tool classification

Every tool is classified under Meta's Muse connector guidelines (sections 3.2, 5.4 and 5.6):

• Read changes nothing anyone can observe. Safe to call without asking.
• Write changes stored state or moves credit back to the person, but buys nothing and contacts no one. A tool that reads and also writes is a Write: the status lookups that settle a refund on the ledger are Writes, and so is create_topup_link, which creates a Stripe Checkout session but charges nothing until the person pays on Stripe's page.
• Sensitive write is irreversible or consequential: a charge, a send, a booking, a dispatched driver, a cancellation or a deletion. It needs the person's explicit approval of what the connector brief lists for that tool.

Each connector brief has the full table per tool: class, side effects, cost, approval, key scope, REST route and per-tool rate limits. The same facts are in every OpenAPI operation as x-muse-classification, and the MCP annotations agree: readOnlyHint is true only on a Read, and destructiveHint is true on every Sensitive write and on nothing else, so clients that always prompt for destructive tools ask before each one. Key scope is separate from class: a read key can call every Read and the Writes that only create a checkout link or settle a refund; everything else needs read,write.

Errors

Every error has the same envelope, whichever connector produced it:

{ "error": { "code": "invalid_request", "message": "..." } }

Credits

One prepaid balance in integer cents covers mail, fax, confirmed restaurant tables, shipping labels, photo prints, greeting cards, and signature envelopes. Bookings are free and never touch it.

Buy a single letter on its own, or a pack. Every pack credits more than it costs, and the bonus is ordinary credit.

The free letters are the bonus divided by the $2.49 first-page letter price; spend it on postcards or faxes if you prefer. get_balance and create_topup_link both return this table as packs, and so does the insufficient_credits body, each entry { "label", "pay_cents", "credits_cents", "free_letters" }. Paying an amount that is not on the list credits exactly what was paid.

Idempotency

Put an idempotency_key (a string up to 128 characters) on every send and every booking. For 24 hours, a repeat of the same key with the same body returns the original response instead of acting again. The same key with a different body returns 409 idempotency_conflict. Use one key per human request, not per retry.

Mail

Types

type Address = {
  name: string;            // 1..40 chars, required for send, optional for verify
  company?: string;        // <= 40
  line1: string;           // <= 64
  line2?: string;          // <= 64
  city: string;
  state: string;           // 2-letter
  zip: string;             // 5 or 9 digits
  country?: "US";          // US only in v0
};

type MailStatus = "created" | "processing" | "in_transit" | "delivered" | "returned" | "failed" | "cancelled";

type MailRecord = {
  mail_id: string;                 // "ml_<id>"
  kind: "letter" | "postcard";
  status: MailStatus;
  to: Address;
  from: Address;
  created_at: string;              // ISO 8601
  expected_delivery_date?: string; // YYYY-MM-DD
  credits_charged_cents: number;
  tracking_url?: string;
};

Endpoints

• verify_address - in { "address": Address } (name optional), out { "deliverable": boolean, "normalized": Address, "notes": string[] }. Use the normalized address when you send.
• estimate_cost - in { "kind": "letter" | "postcard", "pages"?: number, "color"?: boolean, "certified"?: boolean }, out { "total_cents": number, "breakdown": [{ "item": string, "cents": number }] }.
• send_letter - in to, from, optional subject (<= 120 chars), exactly one of body_markdown, body_html or pdf_url (<= 20 KB), plus color, double_sided, certified and idempotency_key. Out: a MailRecord plus balance_cents. Markdown is rendered to simple HTML; HTML is sanitized, so scripts are stripped and images load by URL.
• send_postcard - in to, from, front (text and/or image_url), message (<= 350 characters), idempotency_key. Out: same shape as send_letter.
• get_mail_status - in { "mail_id" }, out a MailRecord plus { "events": [{ "at": string, "status": MailStatus, "detail"?: string }] }.
• list_sent_mail - in { "limit"?: 1..50, "cursor"?: string } (default 20), out { "items": MailRecord[], "next_cursor"?: string }.
• get_balance - out { "balance_cents": number, "currency": "usd", "topup_url": string, "packs": CreditPack[] }.
• create_topup_link - in { "amount_cents": 249 | 1000 | 2500 | 5000 } (one of those, cheapest first is the one-off single letter), out { "checkout_url": string, "expires_at": string, "packs": CreditPack[] }. A CreditPack is { "label", "pay_cents", "credits_cents", "free_letters" }; see Credits.
• GET /me - out { "account_id", "email", "scope", "key_prefix", "balance_cents" }.

The server validates, estimates, checks your balance, charges, then calls the print provider. If the provider fails after the charge, the credits are refunded and you get 502 provider_error.

Fax

Types

type FaxStatus = "queued" | "sending" | "delivered" | "failed";

Endpoints

• estimate_fax_cost - in { "pages": 1..50 }, out { "total_cents", "breakdown" }.
• send_fax - in to_number (E.164, US or CA), optional recipient_name, exactly one of pdf_url or body_markdown, optional cover_note (<= 500 characters) and idempotency_key. Out { "fax_id", "status", "pages_estimated", "credits_charged_cents", "balance_cents", "to_number" }.
• get_fax_status - out a fax record plus events[]. A fax that ends in failed is refunded once.
• list_faxes, get_balance, create_topup_link - as in mail. The balance and top-up endpoints read and write the same ledger.

If you supply body_markdown and the configured provider will not accept rendered HTML, the server returns 400 invalid_request with field: "body_markdown" and a message telling you to supply a pdf_url.

Page counts come from the provider when available. Otherwise the server estimates one page per 3,000 characters and trues up the charge when the provider reports the final count, recording the adjustment on the ledger.

Restaurant tables

For restaurants that have no booking API. You supply the restaurant and its phone number; we call or text it, get a yes or a no, and report back. We are not the restaurant. Nothing is a reservation until the restaurant says it is.

Types

type TableStatus =
  | "requested" | "contacting"
  | "confirmed" | "declined" | "no_answer" | "cancelled" | "failed";

The last five are terminal and never change again.

Endpoints

• request_table - in restaurant_name, restaurant_phone (E.164, US only), party_size (1 to 20), requested_at (ISO with its UTC offset, in the future), diner_name, optional diner_phone, notes (<= 200 characters) and idempotency_key. Out { "request_id", "status": "contacting", "channel", "expires_at", "price_cents_if_confirmed", "balance_cents", "tables_balance_cents" }.
• get_table_request - out the record plus events[]. This is how you find out whether the restaurant answered.
• cancel_table_request - allowed only while requested or contacting. Free.
• get_balance and create_topup_link - as in mail and fax, plus tables_balance_cents (leftover credit from a table pass bought before tables became free). create_topup_link takes exactly one of amount_cents or fax_bundle_cents. Neither is needed to ask for a table.

Asking for a table is free for the person and their agent, whatever the restaurant answers. request_table needs no credit and never returns 402; price_cents_if_confirmed is always 0. Restaurants pay us to be bookable, $25.00 a month or $150.00 a year.

A request expires an hour before the table or two hours after it was made, whichever comes first, floored at ten minutes. There is no retry.

Two further routes under /c/tables/v1 are not tools and take no API key: POST /c/tables/v1/restaurants/opt-in and GET /c/tables/v1/restaurants/count are the restaurant sign-up form and its counter on for restaurants.

Shipping labels

US shipping labels through our provider, EasyPost: quote a package, buy a label, make a return label, book a USPS pickup, track any package from any carrier, and void an unused label. Shipping spends ordinary credit only.

Types

ShipAddress is the mail Address with name required, plus optional phone and email. Parcel is { "weight_oz", "length_in"?, "width_in"?, "height_in"?, "preset"? }: the weight is always required, the three dimensions come together or not at all, and preset (envelope, small_box, medium_box, large_box, flat_rate_envelope, small_flat_rate_box, medium_flat_rate_box, large_flat_rate_box) replaces the dimensions.

Endpoints

• get_shipping_rates - in { "from", "to", "parcel", "return_label"? }. Checks both addresses with the carrier (an undeliverable to is 400 with field: "to"), then returns up to six quotes, cheapest first, each { "quote_id", "carrier", "service", "delivery_days", "price_cents", "retail_cents", "qr_code_available" }, plus expires_at (60 minutes) and balance_cents.
• buy_label / create_return_label - in { "quote_id", "confirm": true, "qr_code"?, "idempotency_key"? }. A quote is single-use. qr_code defaults to true for returns and applies to USPS only. Out the shipment with label_url (PDF) and qr_code_url (PNG for the USPS counter). A carrier refusal is 502 after an automatic refund.
• void_label - in { "shipment_id", "confirm": true }, only for an unscanned label. It sets refund_status: "submitted"; credits return when the carrier confirms. USPS: within 30 days, at least 15 days to process.
• get_pickup_options / schedule_pickup / cancel_pickup - a pickup at the shipment's origin in a window you give. USPS Package Pickup is free.

A label is priced ceil(rate_cents * 142 / 100) + 150 from the carrier's rate. See pricing for the comparison with the post office counter.

Photo prints

Photos printed by a photo lab and posted to a US address: 4x6, 5x7 and 8x10 prints, a 12x16 canvas, a custom T-shirt with the photo on the front and a custom 11oz mug with the photo wrapped around it. Shirts and mugs are printed on demand and are not returnable except when damaged or misprinted. Quote first, then order the quote.

Types

type PrintStatus = "submitted" | "in_production" | "shipped" | "cancelled";
type PrintProduct = "4x6" | "5x7" | "8x10" | "canvas-12x16" | "tshirt" | "mug-11oz";
type ShirtSize = "XS" | "S" | "M" | "L" | "XL" | "2XL" | "3XL";
type ShirtColor = "White" | "Black";

Endpoints

• upload_print_image - in image_base64 (JPEG or PNG, up to 20 MB). Out image_id, the pixel size and how sharp it prints at each size. Deleted after 24 hours unless ordered.
• quote_prints - in items[] (product, copies, and one of image_id or a public https image_url; a tshirt item also needs shirt_size and shirt_color), shipping_method (budget, standard, express) and a US recipient. Out quote_id, total_cents, breakdown[] and warnings[] for photos that will print soft or be trimmed. Valid 24 hours.
• order_prints - in quote_id and confirm: true. Charges exactly the quote's total_cents. The same quote_id never orders twice.
• cancel_print_order - only before the lab starts printing; refunds in full.

Greeting cards

Mail a real greeting card to a US address. Two tiers: handwritten, a folded card written by a robot holding a real pen, in a hand-addressed and stamped envelope; and printed, a 6x9 postcard-style card with the message on the back. A printed card is an open postcard: anyone who handles it can read the message, so offer the handwritten tier for sympathy cards and anything private.

Types

type CardStatus =
  | "scheduled" | "submitted" | "in_production" | "mailed" | "delivered"
  | "returned" | "cancelled" | "failed";

Endpoints

• preview_card - in design_id, message (1 to 320 characters handwritten, 1 to 500 printed), optional signoff and handwriting_style, to and from addresses with names, and at most one of send_on or arrive_by (YYYY-MM-DD). Out a single-use quote_id valid 24 hours, with the price, the dispatch date and the estimated arrival window. Nothing is charged.
• send_card - in { "quote_id", "confirm": true }. The quote_id is the idempotency key: a repeat never mails or charges twice.
• cancel_card - a scheduled card is cancelled and refunded at once; a card already with the provider only while the provider still allows it.
• get_balance and create_topup_link - as in mail. Cards spend ordinary credit only.
• delete_my_data - reduces every card's addresses to city, state and ZIP3 and deletes messages and quotes at once. A scheduled card is cancelled and refunded first.

Arrive by a date. arrive_by dispatches 8 days earlier for handwritten and 7 for printed; we hold the paid card until then, so it can be cancelled for a full refund until it leaves. Addresses and messages are deleted 30 days after a card is mailed.

Signatures

Get a PDF signed by up to 5 people, or sign one yourself, under the US ESIGN Act and UETA. Our own signing page, no e-signature partner. We send no email: send_envelope returns each signer's signing_url, and the agent delivers it from the human's own email connector, so the request comes from someone the signer knows. Full details, including the documents that may not be sent, are in the connector brief.

Endpoints

• create_envelope - in title, exactly one of document_url (https) or document_base64, and signers (1 to 5, each name, email, optional order), or self_sign: true with signer_name. Optional fields, message, expires_in_days (1 to 90) and retention_days (30, 90, 365 or 1095). Out: the draft and a quote with quote_id and total_cents, valid 24 hours.
• send_envelope - in envelope_id and quote_id. Charges exactly the quoted amount, once. Out: each signer with their signing_url. Links are shown only here and from remind_signer.
• void_envelope - full refund if no signer has opened their link yet; otherwise free but not refunded.
• get_signed_document - a download link for the finished PDF, valid 15 minutes.

Bookings

Free for the person booking. No call in this connector deducts credits. Merchants pay $29.00 a month to be listed; see for businesses.

Endpoints

• search_providers - in { "query": string, "city"?: string, "state"?: string, "zip"?: string, "limit"?: 1..20 }, out { "providers": [...] } with provider_id, display_name, categories, address, timezone, next_available_at and services_preview. Matching is a case-insensitive keyword match over service names and categories, filtered by city and state or ZIP prefix. Radius search does not exist in v0.
• list_services - out { "services": [...] } with service_id, name, duration_min, price_cents, optional description and team_member_ids. Cached, refreshed when older than ten minutes.
• get_availability - in { "service_id", "date_from": "YYYY-MM-DD", "date_to": "YYYY-MM-DD", "team_member_id"? }, a window of at most 14 days. Out { "slots": [...] }, at most 50, each with start_at (ISO with offset), team_member_id and duration_min.
• create_booking - in provider_id, service_id, start_at, optional team_member_id, a customer block (given_name, family_name, email, phone in E.164), optional note (<= 200 characters) and idempotency_key. Out booking_id, status (pending, confirmed or cancelled), confirmation, start_at, end_at, provider, service and cancellation_policy. A new booking is a request: it comes back pending, the business accepts it in their own Square calendar, usually the same day, and confirmation is the sentence to read to the person.
• get_booking - out the same booking object. It re-reads the status from the business's calendar, so this is how you find out whether a pending request has been accepted.
• cancel_booking - in { "booking_id", "reason"? }, out the booking with status: "cancelled".
• list_my_bookings - in { "limit"?, "cursor"? }, out { "items": [booking], "next_cursor"? } for the calling account only.

Merchant endpoints

These are for business owners in a browser, not for agents:

• GET https://api.noerrands.com/c/booking/merchant/connect?merchant_email=&return_to= starts Square OAuth.
• GET https://api.noerrands.com/c/booking/merchant/callback is the OAuth redirect target. It sends a browser on to /for-businesses/connected with merchant, status and trial_until on the query; a caller sending Accept: application/json gets the JSON body instead, including the merchant session token.
• GET/PATCH https://api.noerrands.com/c/booking/merchant/me is merchant self-service, authenticated with a merchant session token rather than an API key. GET also returns billing_status, trial_until and plan_url.
• POST https://api.noerrands.com/c/booking/merchant/manage-link with { "email": "..." } asks for a single-use, 24-hour link to /for-businesses/manage, the settings page a business uses to check its listing and disconnect. It always answers 202 and never says whether the address is connected.
• POST https://api.noerrands.com/c/booking/merchant/disconnect revokes at Square and deletes everything we hold about that business.
• POST https://api.noerrands.com/c/booking/square/webhook receives Square's event notifications. We subscribe to oauth.authorization.revoked, so a business that disconnects inside Square is deleted here within seconds.

Test it with curl

Set your key once:

export API_KEY="ne_live_your_key_here"
export MAIL="https://api.noerrands.com/c/mail/v1"
export FAX="https://api.noerrands.com/c/fax/v1"
export BOOKING="https://api.noerrands.com/c/booking/v1"

Is the service up?

curl -s https://api.noerrands.com/health

Check the account and the balance:

curl -s "$MAIL/me" -H "Authorization: Bearer $API_KEY"
curl -s "$MAIL/balance" -H "Authorization: Bearer $API_KEY"

Check a postal address (free):

curl -s "$MAIL/addresses/verify" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"address":{"name":"Ada Lovelace","line1":"1 Main St","city":"Austin","state":"TX","zip":"78701"}}'

Get a price (free):

curl -s "$MAIL/estimate" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"letter","pages":2,"color":false,"certified":false}'

curl -s "$FAX/estimate" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pages":3}'

Send a letter (this costs money):

curl -s "$MAIL/letters" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to":{"name":"Ada Lovelace","line1":"1 Main St","city":"Austin","state":"TX","zip":"78701"},
    "from":{"name":"Grace Hopper","line1":"2 Oak Ave","city":"Denver","state":"CO","zip":"80202"},
    "subject":"Hello",
    "body_markdown":"Dear Ada,\n\nThank you.\n\nGrace",
    "idempotency_key":"letter-to-ada-2026-09-21"
  }'

Send a postcard (this costs money):

curl -s "$MAIL/postcards" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to":{"name":"Ada Lovelace","line1":"1 Main St","city":"Austin","state":"TX","zip":"78701"},
    "from":{"name":"Grace Hopper","line1":"2 Oak Ave","city":"Denver","state":"CO","zip":"80202"},
    "front":{"text":"Greetings from Denver"},
    "message":"Wish you were here.",
    "idempotency_key":"postcard-to-ada-2026-09-21"
  }'

Send a fax (this costs money):

curl -s "$FAX/faxes" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to_number":"+14155550123",
    "recipient_name":"Records Office",
    "pdf_url":"https://example.com/intake-form.pdf",
    "cover_note":"Intake form for Ada Lovelace.",
    "idempotency_key":"fax-to-records-2026-09-21"
  }'

Find a business and see its open slots (free):

curl -s "$BOOKING/providers/search" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"haircut","city":"Austin","state":"TX","limit":5}'

curl -s "$BOOKING/providers/prv_01H8X/services" -H "Authorization: Bearer $API_KEY"

curl -s "$BOOKING/providers/prv_01H8X/availability" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"service_id":"svc_01","date_from":"2026-09-24","date_to":"2026-09-26"}'

Book it (free, but it puts a real person in a real calendar):

curl -s "$BOOKING/bookings" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider_id":"prv_01H8X",
    "service_id":"svc_01",
    "start_at":"2026-09-24T14:00:00-05:00",
    "customer":{"given_name":"Ada","family_name":"Lovelace","email":"ada@example.com","phone":"+14155550123"},
    "idempotency_key":"haircut-2026-09-24"
  }'

Check on things:

curl -s "$MAIL/mail/ml_01H8X" -H "Authorization: Bearer $API_KEY"
curl -s "$FAX/faxes/fx_01H8X" -H "Authorization: Bearer $API_KEY"
curl -s "$BOOKING/bookings?limit=5" -H "Authorization: Bearer $API_KEY"

Add credits:

curl -s "$MAIL/topups" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount_cents":249}'

On Windows PowerShell, use Invoke-RestMethod or wrap the JSON in single quotes with curl.exe rather than the curl alias.

Known gaps in v0

• Email addresses on key creation are not verified.
• Mail is United States only; fax is United States and Canada; bookings are United States only; signatures are for use in the United States.
• Signature envelopes send no email: the agent delivers each signing link from the human's own email connector.
• Mail cannot be cancelled once it is submitted to the print provider, and a fax cannot be recalled once transmitted.
• Booking search has no radius filter. Supply a city and state, or a ZIP.
• There is no reschedule call. Cancel and rebook.
• Merchant listings are billed monthly through a Stripe subscription; there is no customer portal link yet, so cancellations go through support.
• Per-call payment over Stripe's Machine Payments Protocol is behind a flag and may return a stubbed challenge.

Support

Email support@noerrands.com.