{"openapi":"3.1.0","info":{"title":"Respan Monitoring (BYOK) API","version":"0.1.0","description":"Respan Monitoring (BYOK) lets an AI assistant read your own Respan Monitoring data through the Respan Monitoring API with a key you supply (Respan API key (read permission is enough)). Read-only: 9 tools (list_error_groups, list_incidents, list_behaviors, list_custom_behaviors, get_custom_behavior, get_behavior_summary, list_limit_policies, get_limit_policy, list_credit_transactions). The BYOK...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-respan-monitoring.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-respan-monitoring/docs"},"termsOfService":"https://connectorbay.com/byok-respan-monitoring/terms"},"servers":[{"url":"https://byok-respan-monitoring.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-respan-monitoring/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_error_groups":{"post":{"operationId":"list_error_groups","summary":"List failed requests grouped by error fingerprint for a time range (up to 200 groups, most failures first) with error cl","description":"List failed requests grouped by error fingerprint for a time range (up to 200 groups, most failures first) with error class, provider, endpoint, HTTP status, count, first and last seen and triage state. Use for \"What are the most frequent LLM errors in Respan this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Range start as an ISO 8601 time, for example 2026-10-01T00:00:00Z. Defaults to 7 days ago.","title":"Start Time"},"end_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Range end as an ISO 8601 time. Defaults to now.","title":"End Time"},"environment":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only this environment, such as prod or test. Leave empty for all environments.","title":"Environment"},"fault_domain":{"anyOf":[{"enum":["user","respan","provider","none"],"type":"string"},{"type":"null"}],"default":null,"description":"Only this fault domain: user, respan, provider or none.","title":"Fault Domain"},"provider":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only errors from this provider id, for example openai.","title":"Provider"},"status":{"anyOf":[{"maximum":599,"minimum":100,"type":"integer"},{"type":"null"}],"default":null,"description":"Only errors with this HTTP status code, for example 429.","title":"Status"}},"title":"list_error_groupsArguments","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_incidents":{"post":{"operationId":"list_incidents","summary":"List windows where the error rate rose well above normal, newest first, with severity, state, peak and baseline error ra","description":"List windows where the error rate rose well above normal, newest first, with severity, state, peak and baseline error rate, error and request counts and dominant error class. Use for \"Were there any LLM error incidents in Respan recently\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_size":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Incidents per page (1 to 200).","title":"Page Size"},"start_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Range start as an ISO 8601 time, for example 2026-10-01T00:00:00Z. Defaults to 7 days ago.","title":"Start Time"},"end_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Range end as an ISO 8601 time. Defaults to now.","title":"End Time"},"environment":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only this environment, such as prod or test. Leave empty for all environments.","title":"Environment"},"fault_domain":{"anyOf":[{"enum":["user","respan","provider","none"],"type":"string"},{"type":"null"}],"default":null,"description":"Only this fault domain: user, respan, provider or none.","title":"Fault Domain"},"state":{"anyOf":[{"enum":["ongoing","past"],"type":"string"},{"type":"null"}],"default":null,"description":"Only incidents that are ongoing or past.","title":"State"},"severity":{"anyOf":[{"enum":["low","medium","high","critical"],"type":"string"},{"type":"null"}],"default":null,"description":"Only incidents of this severity.","title":"Severity"}},"title":"list_incidentsArguments","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_behaviors":{"post":{"operationId":"list_behaviors","summary":"List the behaviors switched on for the workspace (built-in and custom) with their key, display name and polarity (negati","description":"List the behaviors switched on for the workspace (built-in and custom) with their key, display name and polarity (negative issue, positive win or neutral). Use for \"Which behaviors does Respan track for my spans\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_behaviorsArguments","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_behaviors":{"post":{"operationId":"list_custom_behaviors","summary":"List the custom behavior definitions of the workspace (name, plain-language description, polarity, tags, dates), most re","description":"List the custom behavior definitions of the workspace (name, plain-language description, polarity, tags, dates), most recently updated first. Use for \"Which custom behaviors have I defined in Respan\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Behaviors per page (1 to 1000).","title":"Page Size"}},"title":"list_custom_behaviorsArguments","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_custom_behavior":{"post":{"operationId":"get_custom_behavior","summary":"Get one custom behavior definition with its description, polarity and tags. Use for \"Show the Respan custom behavior 6f1","description":"Get one custom behavior definition with its description, polarity and tags. Use for \"Show the Respan custom behavior 6f1c2a9e\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Custom behavior id, as returned by list_custom_behaviors.","maxLength":200,"title":"Id","type":"string"}},"required":["id"],"title":"get_custom_behaviorArguments","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_behavior_summary":{"post":{"operationId":"get_behavior_summary","summary":"Count how often each behavior fired in a time range, with spans scored, spans where a behavior fired, totals per polarit","description":"Count how often each behavior fired in a time range, with spans scored, spans where a behavior fired, totals per polarity and net sentiment. Use for \"How often did my LLM behaviors fire in Respan this week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Range start as an ISO 8601 time, for example 2026-10-01T00:00:00Z. Defaults to 7 days ago.","title":"Start Time"},"end_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Range end as an ISO 8601 time. Defaults to now.","title":"End Time"},"environment":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only this environment, such as prod or test. Leave empty for all environments.","title":"Environment"}},"title":"get_behavior_summaryArguments","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_limit_policies":{"post":{"operationId":"list_limit_policies","summary":"List spend and usage limit policies with scope, metric (cost, tokens or requests), period, rules, threshold and the live","description":"List spend and usage limit policies with scope, metric (cost, tokens or requests), period, rules, threshold and the live counter of the current window. Use for \"Which spend limits are set in Respan and how much of each is used\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_size":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Policies per page (1 to 200).","title":"Page Size"},"sort_by":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":"-updated_at","description":"Sort field; prefix with - for descending.","title":"Sort By"}},"title":"list_limit_policiesArguments","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_limit_policy":{"post":{"operationId":"get_limit_policy","summary":"Get one limit policy with its scope, metric, period, rules, threshold and live counter. Use for \"Show the Respan limit p","description":"Get one limit policy with its scope, metric, period, rules, threshold and live counter. Use for \"Show the Respan limit policy pol_1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Limit policy id, as returned by list_limit_policies.","maxLength":200,"title":"Id","type":"string"}},"required":["id"],"title":"get_limit_policyArguments","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_credit_transactions":{"post":{"operationId":"list_credit_transactions","summary":"List credit ledger lines of the account (id, amount, type, description, date), newest first. Use for \"What credit transa","description":"List credit ledger lines of the account (id, amount, type, description, date), newest first. Use for \"What credit transactions does my Respan account have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_size":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Transactions per page (1 to 1000).","title":"Page Size"}},"title":"list_credit_transactionsArguments","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}}}}