{"openapi":"3.1.0","info":{"title":"BaubleBar API (Bowmark)","version":"e833508f87ff","description":"BaubleBar's personalized jewelry — every product, its size/color variants and real prices, PLUS the free-text personalizer's own character rules and the current made-to-order ship-by date — read off the live Shopify storefront, plus a live-validated checkout handoff link carrying the personalization.\n\nEvery function Bowmark has for BaubleBar (baublebar.com) as one HTTP call. Each runs on Bowmark's infrastructure with the same billing, rules and response envelope as `POST /v1/run`. The whole API: https://api.bowmark.ai/openapi.json. Guide: https://bowmark.ai/docs/api.","contact":{"email":"support@bowmark.ai","url":"https://bowmark.ai/docs/api"}},"servers":[{"url":"https://api.bowmark.ai"}],"security":[{"bearer":[]},{"apiKeyHeader":[]}],"paths":{"/v1/sites/baublebar/search":{"post":{"operationId":"search","summary":"Free-text product search on BaubleBar — \"earrings\", \"gold hoops\", \"initial necklace\" — in the store's own relevance order, each hit carrying every variant with its id, price and live stock.","description":"Free-text product search on BaubleBar — \"earrings\", \"gold hoops\", \"initial necklace\" — in the store's own relevance order, each hit carrying every variant with its id, price and live stock. The entry door from a shopper's words straight to products; at most 10 hits (the storefront's own predictive-search cap).\n\nCalls `bowmark.providers.baublebar.search`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<BaublebarSearchHit[]>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","description":"TypeScript: `string`"},"opts":{"type":"object","properties":{"inStockOnly":{"type":"boolean"},"limit":{"type":"number"}},"additionalProperties":true,"description":"TypeScript: `{ inStockOnly?: boolean; limit?: number }`"}},"required":["query"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/baublebar/listBaublebarCollections":{"post":{"operationId":"listBaublebarCollections","summary":"The entry door: reads BaubleBar's own published list of collections — e.g.","description":"The entry door: reads BaubleBar's own published list of collections — e.g. \"Tennis Bracelets\", \"Personalized Jewelry\" — with each one's handle and product count, so a caller holding only what a shopper would say can find the handle listBaublebarProducts takes.\n\nCalls `bowmark.providers.baublebar.listBaublebarCollections`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<BaublebarCollectionRow[]>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"opts":{"type":"object","properties":{"limit":{"type":"number"}},"additionalProperties":true,"description":"TypeScript: `{ limit?: number }`"}},"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/baublebar/listBaublebarProducts":{"post":{"operationId":"listBaublebarProducts","summary":"Reads a BaubleBar collection's live products — e.g.","description":"Reads a BaubleBar collection's live products — e.g. \"tennis-bracelets\", \"personalized-jewelry\", \"name-initial-jewelry\" — with handle, title, price range and stock. The catalog page is the line and the parse is the unit of work.\n\nCalls `bowmark.providers.baublebar.listBaublebarProducts`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<BaublebarCatalogueRow[]>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"collectionHandle":{"type":"string","description":"TypeScript: `string`"},"opts":{"type":"object","properties":{"limit":{"type":"number"}},"additionalProperties":true,"description":"TypeScript: `{ limit?: number }`"}},"required":["collectionHandle"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/baublebar/getBaublebarProduct":{"post":{"operationId":"getBaublebarProduct","summary":"Reads one product by its handle — every size/color variant with live price and stock, plus (when the product has a free-text personalizer) its exact character-count/allowed-character rules and the cur","description":"Reads one product by its handle — every size/color variant with live price and stock, plus (when the product has a free-text personalizer) its exact character-count/allowed-character rules and the current made-to-order ship-by date. THROWS on an unknown handle (the store answers a real 404).\n\nCalls `bowmark.providers.baublebar.getBaublebarProduct`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<BaublebarProduct>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"handle":{"type":"string","description":"TypeScript: `string`"}},"required":["handle"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/baublebar/getBaublebarCheckoutLink":{"post":{"operationId":"getBaublebarCheckoutLink","summary":"Resolves a product handle + size/color + personalization text to a real Shopify cart-permalink URL carrying the customization as a line-item property, validated live against the storefront's own stock","description":"Resolves a product handle + size/color + personalization text to a real Shopify cart-permalink URL carrying the customization as a line-item property, validated live against the storefront's own stock AND character rules. THROWS if the handle is unknown, if size/color don't resolve to exactly one in-stock variant, or if the text fails the product's own min/max-length or allowed-character rule — the error names the concrete options or the exact rule that failed.\n\nCalls `bowmark.providers.baublebar.getBaublebarCheckoutLink`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<BaublebarCheckoutLink>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"handle":{"type":"string","description":"TypeScript: `string`"},"selections":{"type":"object","properties":{"size":{"type":"string"},"color":{"type":"string"},"text":{"type":"string"}},"additionalProperties":true,"description":"TypeScript: `{ size?: string; color?: string; text?: string }`"},"opts":{"type":"object","properties":{"quantity":{"type":"number"}},"additionalProperties":true,"description":"TypeScript: `{ quantity?: number }`"}},"required":["handle","selections"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Your Bowmark API key."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-Bowmark-Key"}},"responses":{"NotFound":{"description":"No such site or function.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}},"schemas":{"RunEnvelope":{"type":"object","description":"What a run returns. `status` says whether the SCRIPT succeeded. A script that threw or paused for a login is still HTTP 200. Branch on `status`, not on the HTTP code.","required":["ok","status","result","logs","error","ms"],"properties":{"runId":{"type":"string","description":"Stable id for this run. Quote it in a support or `report` message."},"ok":{"type":"boolean","description":"False only when the run produced nothing usable."},"status":{"type":"string","enum":["ok","error","partial","needs_user"],"description":"`partial`: the result is real but some calls failed (see `incomplete`); `ok` stays true. `needs_user`: a person must sign in to a site first. Relay `meta.handoff.url` to them, then run again."},"egress":{"type":"string","enum":["default","link"],"description":"The egress the run was given, present only when the request asked for one. `link`: every request went through the caller's own Chrome (Bowmark Buddy)."},"result":{"description":"Whatever the script `return`ed. Any JSON value."},"logs":{"type":"array","items":{"type":"string"},"description":"Lines the script wrote with `log(...)`."},"error":{"type":["string","null"],"description":"Why the run failed, in plain words. Null on success."},"ms":{"type":"integer","description":"How long the script itself ran, in milliseconds."},"queuedMs":{"type":"integer","description":"How long the run waited for a worker before starting. Present only when it was a second or more."},"needs":{"type":"array","description":"The sign-ins this script is waiting on. Present when `status` is `needs_user`.","items":{"type":"object","required":["capability","provider","providerTitle","kind"],"properties":{"capability":{"type":"string"},"provider":{"type":"string"},"providerTitle":{"type":"string","description":"The site's name, to show a person."},"kind":{"type":"string"}}}},"incomplete":{"type":"object","description":"Present only when `status` is `partial`: which calls did not answer.","properties":{"summary":{"type":"string"},"totalCalls":{"type":"integer"}},"additionalProperties":true},"emptyHanded":{"type":"object","description":"Present when the script returned nothing while its calls returned rows, usually a filter that matched none of the site's own labels. Lists the label values the calls actually returned.","additionalProperties":true},"notes":{"type":"array","description":"Caveats a call attached to a complete answer. Never changes `status`.","items":{"type":"object","properties":{"path":{"type":"string"},"notes":{"type":"array","items":{"type":"string"}}}}},"meta":{"type":"object","properties":{"handoff":{"type":"object","description":"A single-use sign-in link for a person to open. Expires at `expiresAt`.","properties":{"ref":{"type":"string"},"url":{"type":"string","format":"uri"},"expiresAt":{"type":"string","format":"date-time"}}},"concurrency":{"type":"object","description":"On a 429: how many runs are in flight and when to retry.","properties":{"limit":{"type":"integer"},"inFlight":{"type":"integer"},"retryAfterSeconds":{"type":"integer"}}}},"additionalProperties":true},"notice":{"type":"object","description":"Set when the account owner has not accepted the current Terms. Relay it to them.","additionalProperties":true}}}}}}