{"openapi":"3.1.0","info":{"title":"Roadie (BYOK) API","version":"0.1.0","description":"Roadie (BYOK) lets an AI assistant read your own Roadie data through the Roadie API with a key you supply (Roadie API token). Read-only: 11 tools (list_entities, query_entities, get_entity, list_entity_facets, list_locations, list_scorecards, get_scorecard, list_scorecard_results, get_scorecard_results, list_tech_insights_checks, list_data_sources). The BYOK key travels with each request, is used...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-roadie.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-roadie/docs"},"termsOfService":"https://connectorbay.com/byok-roadie/terms"},"servers":[{"url":"https://byok-roadie.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-roadie/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_entities":{"post":{"operationId":"list_entities","summary":"List software catalog entities (components, APIs, systems, groups, resources) matching a filter, with name, owner, lifec","description":"List software catalog entities (components, APIs, systems, groups, resources) matching a filter, with name, owner, lifecycle, type and tags. A filter is required. Use for \"Which production components are in our Roadie catalog\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"filter":{"description":"Catalog filter, required, for example 'kind=component,spec.lifecycle=production'. Comma-separated conditions must all match.","maxLength":300,"title":"Filter","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many entities to return (1 to 100).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"How many entities to skip, for paging.","title":"Offset"}},"required":["filter"],"title":"list_entitiesArguments","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/query_entities":{"post":{"operationId":"query_entities","summary":"Search catalog entities with optional filter and free-text term, using cursor paging; returns entities, the total count ","description":"Search catalog entities with optional filter and free-text term, using cursor paging; returns entities, the total count and the next cursor. Use for \"Search the Roadie catalog for entities mentioning 'payments'\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"filter":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Catalog filter, for example 'kind=component,spec.lifecycle=production'. Comma-separated conditions must all match.","title":"Filter"},"full_text":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Free text to look for in entities.","title":"Full Text"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many entities to return (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":1000,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from pageInfo.nextCursor of a previous answer.","title":"Cursor"}},"title":"query_entitiesArguments","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_entity":{"post":{"operationId":"get_entity","summary":"Get one catalog entity by kind, namespace and name, with description, owner, lifecycle, type, tags and its relations. Us","description":"Get one catalog entity by kind, namespace and name, with description, owner, lifecycle, type, tags and its relations. Use for \"Show the payments-api component in the Roadie catalog\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"kind":{"description":"Entity kind in lower case, for example 'component', 'api', 'system', 'group' or 'resource'.","maxLength":200,"title":"Kind","type":"string"},"namespace":{"description":"Entity namespace; 'default' unless the catalog uses others.","maxLength":200,"title":"Namespace","type":"string"},"name":{"description":"Entity name as it appears in the catalog.","maxLength":200,"title":"Name","type":"string"}},"required":["kind","namespace","name"],"title":"get_entityArguments","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_entity_facets":{"post":{"operationId":"list_entity_facets","summary":"Count catalog entities grouped by a field such as kind, spec.type, spec.owner or spec.lifecycle, optionally within a fil","description":"Count catalog entities grouped by a field such as kind, spec.type, spec.owner or spec.lifecycle, optionally within a filter. Use for \"How many Roadie catalog entities are there per kind\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"facet":{"description":"Field to group by, for example 'kind', 'spec.type', 'spec.lifecycle' or 'spec.owner'.","maxLength":100,"title":"Facet","type":"string"},"filter":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Catalog filter, for example 'kind=component,spec.lifecycle=production'. Comma-separated conditions must all match.","title":"Filter"}},"required":["facet"],"title":"list_entity_facetsArguments","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_locations":{"post":{"operationId":"list_locations","summary":"List the catalog locations (source files or URLs the catalog is built from) with type and target. Use for \"Which locatio","description":"List the catalog locations (source files or URLs the catalog is built from) with type and target. Use for \"Which locations feed our Roadie catalog\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_locationsArguments","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_scorecards":{"post":{"operationId":"list_scorecards","summary":"List the Tech Insights scorecards with title, owner, enabled and draft flags and the checks each one uses. Use for \"Whic","description":"List the Tech Insights scorecards with title, owner, enabled and draft flags and the checks each one uses. Use for \"Which Tech Insights scorecards do we have in Roadie\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_scorecardsArguments","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_scorecard":{"post":{"operationId":"get_scorecard","summary":"Get one Tech Insights scorecard with its title, owner, sponsor, flags and checks. Use for \"Show the Roadie scorecard 1b4","description":"Get one Tech Insights scorecard with its title, owner, sponsor, flags and checks. Use for \"Show the Roadie scorecard 1b4e28ba-2fa1-11d2-883f-0016d3cca427\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"scorecard_id":{"description":"Id (UUID) of the Tech Insights scorecard; list_scorecards returns the ids.","maxLength":200,"title":"Scorecard Id","type":"string"}},"required":["scorecard_id"],"title":"get_scorecardArguments","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_scorecard_results":{"post":{"operationId":"list_scorecard_results","summary":"List the overall result of every Tech Insights scorecard: entities and checks counted, and how many pass or fail. Use fo","description":"List the overall result of every Tech Insights scorecard: entities and checks counted, and how many pass or fail. Use for \"How are our Roadie scorecards doing overall\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_scorecard_resultsArguments","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_scorecard_results":{"post":{"operationId":"get_scorecard_results","summary":"Get the result of one Tech Insights scorecard: entities and checks counted and how many pass or fail. Use for \"What is t","description":"Get the result of one Tech Insights scorecard: entities and checks counted and how many pass or fail. Use for \"What is the pass rate of Roadie scorecard 1b4e28ba-2fa1-11d2-883f-0016d3cca427\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"scorecard_id":{"description":"Id (UUID) of the Tech Insights scorecard; list_scorecards returns the ids.","maxLength":200,"title":"Scorecard Id","type":"string"}},"required":["scorecard_id"],"title":"get_scorecard_resultsArguments","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_tech_insights_checks":{"post":{"operationId":"list_tech_insights_checks","summary":"List the Tech Insights checks with name, description, whether built in, and the data sources they read. Use for \"Which T","description":"List the Tech Insights checks with name, description, whether built in, and the data sources they read. Use for \"Which Tech Insights checks exist in Roadie\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_tech_insights_checksArguments","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_data_sources":{"post":{"operationId":"list_data_sources","summary":"List the Tech Insights data sources (fact collectors) with title, schedule, version and entity filter. Use for \"Which Te","description":"List the Tech Insights data sources (fact collectors) with title, schedule, version and entity filter. Use for \"Which Tech Insights data sources feed Roadie scorecards\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_data_sourcesArguments","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}}}}