{"openapi":"3.1.0","info":{"title":"Scanova (BYOK) API","version":"0.1.0","description":"Scanova (BYOK) lets an AI assistant read your own Scanova data through the Scanova API with a key you supply (Scanova API key (live or sandbox environment; needs a plan with API access)). Read-only: 10 tools (list_qr_codes, get_qr_code, list_folders, list_tags, get_analytics_overview, list_forms, list_lead_lists, list_custom_domains, list_qr_categories, get_current_plan). The BYOK key travels...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-scanova.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-scanova/docs"},"termsOfService":"https://connectorbay.com/byok-scanova/terms"},"servers":[{"url":"https://byok-scanova.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-scanova/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_qr_codes":{"post":{"operationId":"list_qr_codes","summary":"List QR codes with name, static or dynamic type, category, short URL and visit count, tags, folder and dates. Newest fir","description":"List QR codes with name, static or dynamic type, category, short URL and visit count, tags, folder and dates. Newest first by default. Use for \"Which of my Scanova QR codes are dynamic and tagged 'print'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Free text matched against name, qrid, slug and folder name.","title":"Search"},"category":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated category slugs, for example 'url,event'.","title":"Category"},"tags":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated tag names; matches any of them.","title":"Tags"},"type":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated QR types: dy (dynamic) or st (static).","title":"Type"},"folder":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only QR codes in this folder id.","title":"Folder"},"created_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only QR codes created on or after this date (YYYY-MM-DD).","title":"Created From"},"created_till":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only QR codes created on or before this date (YYYY-MM-DD).","title":"Created Till"},"ordering":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Sort fields name, created, qr_type or category__name, comma-separated; prefix - for descending, for example '-created'.","title":"Ordering"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Results per page (default 10, maximum 100).","title":"Page Size"}},"title":"list_qr_codesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_qr_code":{"post":{"operationId":"get_qr_code","summary":"Get one QR code by its qrid (not the numeric id): name, type, category, short URL, visit count, tags and publish state. ","description":"Get one QR code by its qrid (not the numeric id): name, type, category, short URL, visit count, tags and publish state. Use for \"How many scans has Scanova QR code QR7K9M2XN had\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"qrid":{"description":"The QR code's qrid, for example 'QR7K9M2XN', from list_qr_codes.","maxLength":40,"title":"Qrid","type":"string"}},"required":["qrid"],"title":"get_qr_codeArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_folders":{"post":{"operationId":"list_folders","summary":"List QR code folders with name, type (qr or page), color and how many QR codes each holds. Newest first. Use for \"How ma","description":"List QR code folders with name, type (qr or page), color and how many QR codes each holds. Newest first. Use for \"How many QR codes are in each of my Scanova folders\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"folder_type":{"anyOf":[{"enum":["qr","page"],"type":"string"},{"type":"null"}],"default":null,"description":"Only this folder type: qr or page.","title":"Folder Type"},"search":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"Case-insensitive match on folder name.","title":"Search"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Results per page (default 10, maximum 100).","title":"Page Size"}},"title":"list_foldersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_tags":{"post":{"operationId":"list_tags","summary":"List the tags visible to the account (lowercase names). Use for \"Which tags do I use on Scanova QR codes\".","description":"List the tags visible to the account (lowercase names). Use for \"Which tags do I use on Scanova QR codes\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"anyOf":[{"maxLength":50,"type":"string"},{"type":"null"}],"default":null,"description":"Case-insensitive prefix filter on the tag name.","title":"Name"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Results per page (default 10, maximum 100).","title":"Page Size"}},"title":"list_tagsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_analytics_overview":{"post":{"operationId":"get_analytics_overview","summary":"Get account-wide scan totals: all-time scans and QR code count, this month's scans and unique scans, scans by month and ","description":"Get account-wide scan totals: all-time scans and QR code count, this month's scans and unique scans, scans by month and by date. Use for \"How many scans did my Scanova QR codes get this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"type":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated subset of all_time, current_month, last_months, scan_dates; omit for all.","title":"Type"}},"title":"get_analytics_overviewArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_forms":{"post":{"operationId":"list_forms","summary":"List lead-capture forms with name, active flag, how many QR codes use each, entry count, conversion rate and form URL. R","description":"List lead-capture forms with name, active flag, how many QR codes use each, entry count, conversion rate and form URL. Responses themselves are not returned. Use for \"Which Scanova forms have the most entries\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"is_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for active forms only, false for inactive.","title":"Is Active"},"created_from":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Created on or after this date (YYYY-MM-DD).","title":"Created From"},"created_till":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Created on or before this date (YYYY-MM-DD).","title":"Created Till"},"search":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"Free text filter on the form name.","title":"Search"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Results per page (default 10, maximum 100).","title":"Page Size"}},"title":"list_formsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_lead_lists":{"post":{"operationId":"list_lead_lists","summary":"List legacy lead lists with name, active flag, QR codes attached and number of submissions collected. Entries themselves","description":"List legacy lead lists with name, active flag, QR codes attached and number of submissions collected. Entries themselves are not returned. Use for \"How many submissions have my Scanova lead lists collected\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"is_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for active lead lists only, false for inactive.","title":"Is Active"}},"title":"list_lead_listsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_custom_domains":{"post":{"operationId":"list_custom_domains","summary":"List connected custom domains with verification state of the TXT and CNAME records and the CNAME target (plans with cust","description":"List connected custom domains with verification state of the TXT and CNAME records and the CNAME target (plans with custom domains only). Use for \"Are my Scanova custom domains verified\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_custom_domainsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_qr_categories":{"post":{"operationId":"list_qr_categories","summary":"List the QR code categories (website URL, event, business card and so on) with id, slug, supported types and landing-pag","description":"List the QR code categories (website URL, event, business card and so on) with id, slug, supported types and landing-page flag. Use for \"Which QR code categories does Scanova support\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"allowed_qr_types":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated QR types to filter on, for example 'dy' or 'st,dy'.","title":"Allowed Qr Types"}},"title":"list_qr_categoriesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_current_plan":{"post":{"operationId":"get_current_plan","summary":"Get the account's current plan: name, free or paid, expiry date, days left, auto-renewal and the plan family. Use for \"W","description":"Get the account's current plan: name, free or paid, expiry date, days left, auto-renewal and the plan family. Use for \"When does my Scanova plan expire\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_current_planArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}