{"openapi":"3.1.0","info":{"title":"Merge Agent Handler (BYOK) API","version":"0.1.0","description":"Merge Agent Handler (BYOK) lets an AI assistant read your own Merge Agent Handler data through the Merge Agent Handler API with a key you supply (Agent Handler access key). Read-only: 8 tools (list_connectors, get_connector, list_tool_packs, get_tool_pack, list_tool_pack_connectors, list_connections, get_total_usage, list_usage_by_tool). The BYOK key travels with each request, is used for that...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-merge-agent-handler.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-merge-agent-handler/docs"},"termsOfService":"https://connectorbay.com/byok-merge-agent-handler/terms"},"servers":[{"url":"https://byok-merge-agent-handler.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-merge-agent-handler/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_connectors":{"post":{"operationId":"list_connectors","summary":"List or search the Agent Handler connector catalog (third-party tool servers) with categories and each connector's tool ","description":"List or search the Agent Handler connector catalog (third-party tool servers) with categories and each connector's tool names, descriptions and credit type. Use for \"Which Agent Handler connectors exist for project management\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Case-insensitive filter over connector name and slug, for example 'linear'.","title":"Search"},"page":{"anyOf":[{"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":25,"description":"Results per page (1 to 100).","title":"Page Size"}},"title":"list_connectorsArguments","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_connector":{"post":{"operationId":"get_connector","summary":"Get one Agent Handler connector by slug with description, categories and its tools (name, description, credit type). Use","description":"Get one Agent Handler connector by slug with description, categories and its tools (name, description, credit type). Use for \"What tools does the Agent Handler linear connector offer\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"slug":{"description":"Connector slug from list_connectors, for example 'linear'.","maxLength":200,"title":"Slug","type":"string"}},"required":["slug"],"title":"get_connectorArguments","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_tool_packs":{"post":{"operationId":"list_tool_packs","summary":"List your tool packs (bounded sets of connectors and tools handed to an agent) with the connectors and tools enabled in ","description":"List your tool packs (bounded sets of connectors and tools handed to an agent) with the connectors and tools enabled in each. Use for \"Which tool packs have I defined in Agent Handler\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"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":25,"description":"Results per page (1 to 100).","title":"Page Size"}},"title":"list_tool_packsArguments","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_tool_pack":{"post":{"operationId":"get_tool_pack","summary":"Get one tool pack by id with its connectors, auth scope and enabled tools. Use for \"Show Agent Handler tool pack tp_1\".","description":"Get one tool pack by id with its connectors, auth scope and enabled tools. Use for \"Show Agent Handler tool pack tp_1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Tool pack id from list_tool_packs.","maxLength":200,"title":"Id","type":"string"}},"required":["id"],"title":"get_tool_packArguments","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_tool_pack_connectors":{"post":{"operationId":"list_tool_pack_connectors","summary":"List the connectors attached to one tool pack with auth scope and the tools enabled on each. Use for \"Which connectors d","description":"List the connectors attached to one tool pack with auth scope and the tools enabled on each. Use for \"Which connectors does Agent Handler tool pack tp_1 include\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"tool_pack_id":{"description":"Tool pack id from list_tool_packs.","maxLength":200,"title":"Tool Pack Id","type":"string"}},"required":["tool_pack_id"],"title":"list_tool_pack_connectorsArguments","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_connections":{"post":{"operationId":"list_connections","summary":"List authenticated connections to third-party tools with connector, auth type and scope, health status (ACTIVE or ERROR)","description":"List authenticated connections to third-party tools with connector, auth type and scope, health status (ACTIVE or ERROR) and retirement time; owner names are left out. Use for \"Which Agent Handler connections are in error\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":["ACTIVE","ERROR"],"type":"string"},{"type":"null"}],"default":null,"description":"Only connections with this status; comma-separated for several.","title":"Status"},"auth_scope":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"Only this auth scope: INDIVIDUAL, SHARED or ORGANIZATION; comma-separated for several.","title":"Auth Scope"},"connector":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only connections of this connector slug.","title":"Connector"},"page":{"anyOf":[{"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":25,"description":"Results per page (1 to 100).","title":"Page Size"}},"title":"list_connectionsArguments","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_total_usage":{"post":{"operationId":"get_total_usage","summary":"Get total credits used and tool-call count for your organization over a time window of up to 31 days. Use for \"How many ","description":"Get total credits used and tool-call count for your organization over a time window of up to 31 days. Use for \"How many Agent Handler credits did I use between 2026-10-01 and 2026-10-15\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_time":{"description":"Start of the usage window, ISO 8601 with timezone, for example 2026-10-01T00:00:00Z. Not more than 90 days ago; the window is at most 31 days.","maxLength":40,"title":"Start Time","type":"string"},"end_time":{"description":"End of the usage window, ISO 8601 with timezone, for example 2026-10-15T00:00:00Z. Must be in the past.","maxLength":40,"title":"End Time","type":"string"}},"required":["start_time","end_time"],"title":"get_total_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_usage_by_tool":{"post":{"operationId":"list_usage_by_tool","summary":"List credits used and call counts per connector tool over a time window of up to 31 days. Use for \"Which Agent Handler t","description":"List credits used and call counts per connector tool over a time window of up to 31 days. Use for \"Which Agent Handler tools used the most credits in the last two weeks\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"start_time":{"description":"Start of the usage window, ISO 8601 with timezone, for example 2026-10-01T00:00:00Z. Not more than 90 days ago; the window is at most 31 days.","maxLength":40,"title":"Start Time","type":"string"},"end_time":{"description":"End of the usage window, ISO 8601 with timezone, for example 2026-10-15T00:00:00Z. Must be in the past.","maxLength":40,"title":"End Time","type":"string"},"page":{"anyOf":[{"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":25,"description":"Results per page (1 to 100).","title":"Page Size"}},"required":["start_time","end_time"],"title":"list_usage_by_toolArguments","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}}}}