{"openapi":"3.1.0","info":{"title":"DX (BYOK) API","version":"0.1.0","description":"DX (BYOK) lets an AI assistant read your own DX data through the DX API with a key you supply (DX organization token or personal access token). Read-only: 12 tools (list_entities, get_entity, list_entity_types, get_entity_type, list_relations, list_entity_relations, get_entity_scorecards, list_scorecards, get_scorecard, list_initiatives, get_initiative, list_workflows). The BYOK key travels with...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-getdx.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-getdx/docs"},"termsOfService":"https://connectorbay.com/byok-getdx/terms"},"servers":[{"url":"https://byok-getdx.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-getdx/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 (services, packages, teams and other types you define) with type, description, owning tea","description":"List software catalog entities (services, packages, teams and other types you define) with type, description, owning teams, properties and repository aliases. Use for \"Which services are in our DX catalog\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"type":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only entities of this entity type identifier, for example 'service'.","title":"Type"},"search_term":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Match against entity name, identifier and owner names.","title":"Search Term"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many entities per page (default 50).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from response_metadata.next_cursor of the previous answer, to get the next page.","title":"Cursor"}},"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/get_entity":{"post":{"operationId":"get_entity","summary":"Get one catalog entity by identifier: type, name, description, owning teams, properties and aliases. Use for \"Show the p","description":"Get one catalog entity by identifier: type, name, description, owning teams, properties and aliases. Use for \"Show the payment-processing entity in the DX catalog\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"identifier":{"description":"Unique identifier of the entity.","maxLength":200,"title":"Identifier","type":"string"}},"required":["identifier"],"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_types":{"post":{"operationId":"list_entity_types","summary":"List the catalog entity types with their property definitions and which repository aliases they accept. Use for \"Which e","description":"List the catalog entity types with their property definitions and which repository aliases they accept. Use for \"Which entity types does our DX catalog define\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many entity types per page (default 50).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from response_metadata.next_cursor of the previous answer, to get the next page.","title":"Cursor"}},"title":"list_entity_typesArguments","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_type":{"post":{"operationId":"get_entity_type","summary":"Get one catalog entity type with its icon, property definitions and alias settings. Use for \"What properties does the 's","description":"Get one catalog entity type with its icon, property definitions and alias settings. Use for \"What properties does the 'service' entity type have in DX\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"identifier":{"description":"Identifier of the entity type, for example 'service'.","maxLength":100,"title":"Identifier","type":"string"}},"required":["identifier"],"title":"get_entity_typeArguments","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_relations":{"post":{"operationId":"list_relations","summary":"List the relation definitions of the catalog, for example 'service depends on service', with direction labels and cardin","description":"List the relation definitions of the catalog, for example 'service depends on service', with direction labels and cardinality. Use for \"Which relation types exist in our DX catalog\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many relation definitions per page (default 50).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from response_metadata.next_cursor of the previous answer, to get the next page.","title":"Cursor"}},"title":"list_relationsArguments","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_relations":{"post":{"operationId":"list_entity_relations","summary":"List the entities that are related to one entity through one relation definition, for example everything a service depen","description":"List the entities that are related to one entity through one relation definition, for example everything a service depends on. Use for \"What does payments-service depend on in DX\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"entity_identifier":{"description":"Identifier of the entity whose relations to list.","maxLength":200,"title":"Entity Identifier","type":"string"},"relation_identifier":{"description":"Identifier of the relation definition (list_relations returns it).","maxLength":200,"title":"Relation Identifier","type":"string"},"direction":{"anyOf":[{"enum":["incoming","outgoing"],"type":"string"},{"type":"null"}],"default":"outgoing","description":"'outgoing' when the entity is the source of the relation, 'incoming' when it is the target.","title":"Direction"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many related entities per page (1 to 50, default 25).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from response_metadata.next_cursor of the previous answer, to get the next page.","title":"Cursor"}},"required":["entity_identifier","relation_identifier"],"title":"list_entity_relationsArguments","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_scorecards":{"post":{"operationId":"get_entity_scorecards","summary":"Get how one catalog entity does on each scorecard: current level and every check with its pass or fail result and last r","description":"Get how one catalog entity does on each scorecard: current level and every check with its pass or fail result and last run time. Use for \"Which scorecard checks does payment-processing fail in DX\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"identifier":{"description":"Identifier of the entity.","maxLength":200,"title":"Identifier","type":"string"},"only_failing":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to list only checks that did not pass.","title":"Only Failing"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many scorecards per page (default 50).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from response_metadata.next_cursor of the previous answer, to get the next page.","title":"Cursor"}},"required":["identifier"],"title":"get_entity_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/list_scorecards":{"post":{"operationId":"list_scorecards","summary":"List scorecards with type, levels, tags, the entity types they apply to and their checks (with the check logic). Names a","description":"List scorecards with type, levels, tags, the entity types they apply to and their checks (with the check logic). Names and e-mails of editors and admins are not returned. Use for \"Which scorecards do we have in DX\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"include_unpublished":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to include draft scorecards too.","title":"Include Unpublished"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many scorecards per page (default 50).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from response_metadata.next_cursor of the previous answer, to get the next page.","title":"Cursor"}},"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 scorecard with its levels, tags and checks. Names and e-mails of editors and admins are not returned. Use for \"S","description":"Get one scorecard with its levels, tags and checks. Names and e-mails of editors and admins are not returned. Use for \"Show the checks of DX scorecard qjfj1a6cmit4\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Id of the scorecard (list_scorecards returns it).","maxLength":100,"title":"Id","type":"string"}},"required":["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_initiatives":{"post":{"operationId":"list_initiatives","summary":"List initiatives (time-boxed pushes to pass scorecard checks) with priority, due date, progress and remaining effort. Th","description":"List initiatives (time-boxed pushes to pass scorecard checks) with priority, due date, progress and remaining effort. The owner is not returned. Use for \"Which DX initiatives are behind\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"published":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for published initiatives only, false for drafts only.","title":"Published"},"priority":{"anyOf":[{"maximum":4,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only initiatives with this priority (0 to 4, lower is more urgent).","title":"Priority"},"tags":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only initiatives with these tags, comma separated.","title":"Tags"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many initiatives per page (default 50).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from response_metadata.next_cursor of the previous answer, to get the next page.","title":"Cursor"}},"title":"list_initiativesArguments","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_initiative":{"post":{"operationId":"get_initiative","summary":"Get one initiative with its scorecard, priority, due date, progress and remaining effort. The owner is not returned. Use","description":"Get one initiative with its scorecard, priority, due date, progress and remaining effort. The owner is not returned. Use for \"How far along is DX initiative qypefayqpvnf\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Id of the initiative (list_initiatives returns it).","maxLength":100,"title":"Id","type":"string"}},"required":["id"],"title":"get_initiativeArguments","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_workflows":{"post":{"operationId":"list_workflows","summary":"List the workflows (self-service actions) the token may trigger, with scope, trigger type and input parameters. Use for ","description":"List the workflows (self-service actions) the token may trigger, with scope, trigger type and input parameters. Use for \"Which self-service workflows exist in DX\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"scope":{"anyOf":[{"enum":["GLOBAL","ENTITY"],"type":"string"},{"type":"null"}],"default":null,"description":"Only workflows of this scope.","title":"Scope"},"entity_identifier":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only workflows that apply to this catalog entity; use together with scope=ENTITY.","title":"Entity Identifier"}},"title":"list_workflowsArguments","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}}}}