{"openapi":"3.1.0","info":{"title":"Smartlook (BYOK) API","version":"0.1.0","description":"Smartlook (BYOK) lets an AI assistant read your own Smartlook data through the Smartlook API with a key you supply (Smartlook project REST API token). Read-only: 9 tools (get_project_info, get_api_usage, list_events, get_event_details, list_funnels, get_funnel_details, search_sessions, get_session_details, get_visitor_sessions). The BYOK key travels with each request, is used for that one call...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-smartlook.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-smartlook/docs"},"termsOfService":"https://connectorbay.com/byok-smartlook/terms"},"servers":[{"url":"https://byok-smartlook.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-smartlook/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/get_project_info":{"post":{"operationId":"get_project_info","summary":"Show the organization and project the token belongs to (ids and names). Use for \"Which Smartlook project is this token f","description":"Show the organization and project the token belongs to (ids and names). Use for \"Which Smartlook project is this token for\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_project_infoArguments","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_api_usage":{"post":{"operationId":"get_api_usage","summary":"Show how many REST API requests the project has used, in total and per endpoint (plan limits: 20 per hour free, 100 paid","description":"Show how many REST API requests the project has used, in total and per endpoint (plan limits: 20 per hour free, 100 paid, 1000 with the add-on). Use for \"How much of my Smartlook REST API quota have I used\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_api_usageArguments","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_events":{"post":{"operationId":"list_events","summary":"List the events defined in the Smartlook project (id, name, category), optionally for one event category. Use for \"Which","description":"List the events defined in the Smartlook project (id, name, category), optionally for one event category. Use for \"Which events are tracked in my Smartlook project\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"category_id":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"Only events of this category id.","title":"Category Id"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many items to return (API default 10, maximum 100).","title":"Limit"},"after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's pagination.after to get the next page.","title":"After"}},"title":"list_eventsArguments","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_event_details":{"post":{"operationId":"get_event_details","summary":"Get how often one event happened in a date range: total occurrences, unique and new visitors, average per visitor and a ","description":"Get how often one event happened in a date range: total occurrences, unique and new visitors, average per visitor and a histogram. Use for \"How many times did the Checkout event happen last week in Smartlook\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"event_id":{"description":"Id of the event (from list_events).","maxLength":200,"title":"Event Id","type":"string"},"date_from":{"description":"First day to include, YYYY-MM-DD.","maxLength":10,"title":"Date From","type":"string"},"date_to":{"description":"Last day to include, YYYY-MM-DD.","maxLength":10,"title":"Date To","type":"string"},"histogram_interval":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Histogram bucket size as documented by Smartlook (leave empty for the default).","title":"Histogram Interval"}},"required":["event_id","date_from","date_to"],"title":"get_event_detailsArguments","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_funnels":{"post":{"operationId":"list_funnels","summary":"List the funnels defined in the project with their ordered event steps. Use for \"Which funnels do I have in Smartlook\".","description":"List the funnels defined in the project with their ordered event steps. Use for \"Which funnels do I have in Smartlook\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many items to return (API default 10, maximum 100).","title":"Limit"},"after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's pagination.after to get the next page.","title":"After"}},"title":"list_funnelsArguments","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_funnel_details":{"post":{"operationId":"get_funnel_details","summary":"Get a funnel's conversion rate and visitors per step for a date range. The funnel may still be computing; check computat","description":"Get a funnel's conversion rate and visitors per step for a date range. The funnel may still be computing; check computation.isFinished. Use for \"What is the conversion rate of my Smartlook signup funnel this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"funnel_id":{"description":"Id of the funnel (from list_funnels).","maxLength":200,"title":"Funnel Id","type":"string"},"date_from":{"description":"First day to include, YYYY-MM-DD.","maxLength":10,"title":"Date From","type":"string"},"date_to":{"description":"Last day to include, YYYY-MM-DD.","maxLength":10,"title":"Date To","type":"string"},"wait_for_finish":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to let the API wait for the computation to finish.","title":"Wait For Finish"}},"required":["funnel_id","date_from","date_to"],"title":"get_funnel_detailsArguments","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/search_sessions":{"post":{"operationId":"search_sessions","summary":"Search session recordings with one filter (landing_url, exit_url, source_referer, recording_url or recording_date) and g","description":"Search session recordings with one filter (landing_url, exit_url, source_referer, recording_url or recording_date) and get metadata per session. User ids and IP addresses are left out. Use for \"Which Smartlook sessions landed on /pricing last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"filter_name":{"description":"What to filter on: landing_url, exit_url, source_referer, recording_url or recording_date.","enum":["landing_url","exit_url","source_referer","recording_url","recording_date"],"title":"Filter Name","type":"string"},"filter_operator":{"description":"Comparison: is, is_not, contains, not_contains (text filters) or before, after, is (recording_date).","enum":["is","is_not","contains","not_contains","before","after"],"title":"Filter Operator","type":"string"},"filter_value":{"description":"Text to match, or a date (YYYY-MM-DD) for recording_date.","maxLength":300,"title":"Filter Value","type":"string"},"sort_by_start":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"desc","description":"Sort by session start time: asc or desc.","title":"Sort By Start"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many items to return (API default 10, maximum 100).","title":"Limit"},"after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's pagination.after to get the next page.","title":"After"}},"required":["filter_name","filter_operator","filter_value"],"title":"search_sessionsArguments","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_session_details":{"post":{"operationId":"get_session_details","summary":"Get metadata of one session recording: duration, times, pages, referrer, browser, platform, country and the Smartlook pl","description":"Get metadata of one session recording: duration, times, pages, referrer, browser, platform, country and the Smartlook player link. User id and IP are left out. Use for \"Tell me about Smartlook session s1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"session_id":{"description":"Id of the session (from search_sessions).","maxLength":200,"title":"Session Id","type":"string"}},"required":["session_id"],"title":"get_session_detailsArguments","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_visitor_sessions":{"post":{"operationId":"get_visitor_sessions","summary":"List the sessions of one visitor with metadata (times, pages, browser, platform, country). User id and IP are left out. ","description":"List the sessions of one visitor with metadata (times, pages, browser, platform, country). User id and IP are left out. Use for \"What sessions did Smartlook visitor v1 have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"visitor_id":{"description":"Id of the visitor (visitorId of a session).","maxLength":200,"title":"Visitor Id","type":"string"},"sort":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort order of the sessions (asc or desc).","title":"Sort"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many items to return (API default 10, maximum 100).","title":"Limit"},"after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from the previous answer's pagination.after to get the next page.","title":"After"}},"required":["visitor_id"],"title":"get_visitor_sessionsArguments","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}}}}