{"openapi":"3.1.0","info":{"title":"Middesk (BYOK) API","version":"0.1.0","description":"Middesk (BYOK) lets an AI assistant read your own Middesk data through the Middesk API with a key you supply (Middesk API key). Read-only: 10 tools (list_businesses, get_business, get_business_review, list_business_orders, list_business_liens, list_business_policy_results, get_latest_risk_assessment, list_signals, get_business_timeline, list_business_documents). The BYOK key travels with each...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-middesk.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-middesk/docs"},"termsOfService":"https://connectorbay.com/byok-middesk/terms"},"servers":[{"url":"https://byok-middesk.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-middesk/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_businesses":{"post":{"operationId":"list_businesses","summary":"List the businesses in your Middesk account with verification status, tags, external ID and website. The documentation l","description":"List the businesses in your Middesk account with verification status, tags, external ID and website. The documentation lists no filters for this call. Use for \"Which businesses have I submitted to Middesk and what is their status\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_businessesArguments","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_business":{"post":{"operationId":"get_business","summary":"Get one business verification record: status, formation details, website, watchlist hit count, risk level and score, and","description":"Get one business verification record: status, formation details, website, watchlist hit count, risk level and score, and whether the TIN was verified. Taxpayer numbers are not returned. Use for \"What is the verification status and risk level of this business\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"business_id":{"description":"Middesk business ID (UUID) from list_businesses, for example 'b2c3d4e5-f6a7-8901-bcde-f12345678901'.","maxLength":200,"title":"Business Id","type":"string"}},"required":["business_id"],"title":"get_businessArguments","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_business_review":{"post":{"operationId":"get_business_review","summary":"Get the review of a business: the list of verification tasks (name, address, registration, TIN, watchlists and others) w","description":"Get the review of a business: the list of verification tasks (name, address, registration, TIN, watchlists and others) with pass or fail status and messages, plus any analyst summary. Use for \"Which verification checks failed for this business\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"business_id":{"description":"Middesk business ID (UUID) from list_businesses, for example 'b2c3d4e5-f6a7-8901-bcde-f12345678901'.","maxLength":200,"title":"Business Id","type":"string"}},"required":["business_id"],"title":"get_business_reviewArguments","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_business_orders":{"post":{"operationId":"list_business_orders","summary":"List the orders (products requested such as identity, liens, website or tin) placed for a business with status and dates","description":"List the orders (products requested such as identity, liens, website or tin) placed for a business with status and dates. Use for \"What Middesk products have been ordered for this business\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"business_id":{"description":"Middesk business ID (UUID) from list_businesses, for example 'b2c3d4e5-f6a7-8901-bcde-f12345678901'.","maxLength":200,"title":"Business Id","type":"string"},"packages":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated list of packages to filter by.","title":"Packages"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Items per page.","title":"Per Page"}},"required":["business_id"],"title":"list_business_ordersArguments","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_business_liens":{"post":{"operationId":"list_business_liens","summary":"List UCC, tax and judgment liens found for a business with type, state, filing date, status, collateral and principal am","description":"List UCC, tax and judgment liens found for a business with type, state, filing date, status, collateral and principal amount. Use for \"Does this business have any open liens\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"business_id":{"description":"Middesk business ID (UUID) from list_businesses, for example 'b2c3d4e5-f6a7-8901-bcde-f12345678901'.","maxLength":200,"title":"Business Id","type":"string"}},"required":["business_id"],"title":"list_business_liensArguments","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_business_policy_results":{"post":{"operationId":"list_business_policy_results","summary":"List the results of the enabled approval policies applied to a business (policy name, result, whether it matched and was","description":"List the results of the enabled approval policies applied to a business (policy name, result, whether it matched and was executed). Use for \"What did my approval policies decide for this business\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"business_id":{"description":"Middesk business ID (UUID) from list_businesses, for example 'b2c3d4e5-f6a7-8901-bcde-f12345678901'.","maxLength":200,"title":"Business Id","type":"string"}},"required":["business_id"],"title":"list_business_policy_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_latest_risk_assessment":{"post":{"operationId":"get_latest_risk_assessment","summary":"Get the latest scored risk assessment of a business: level, 0 to 100 score, title, narrative and per-dimension scores. N","description":"Get the latest scored risk assessment of a business: level, 0 to 100 score, title, narrative and per-dimension scores. Needs the Risk product on the account. Use for \"What is the latest risk assessment for this business\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"business_id":{"description":"Middesk business ID (UUID) from list_businesses, for example 'b2c3d4e5-f6a7-8901-bcde-f12345678901'.","maxLength":200,"title":"Business Id","type":"string"}},"required":["business_id"],"title":"get_latest_risk_assessmentArguments","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_signals":{"post":{"operationId":"list_signals","summary":"List Signal scores (instant business risk scores) with name, score and reason codes, optionally filtered by date, extern","description":"List Signal scores (instant business risk scores) with name, score and reason codes, optionally filtered by date, external ID or search text. Use for \"Show my recent Middesk Signal scores\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"q":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Search text matched against signals.","title":"Q"},"external_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only signals with this external ID.","title":"External Id"},"start_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only signals from this date (YYYY-MM-DD).","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only signals up to this date (YYYY-MM-DD).","title":"End Date"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"Items per page.","title":"Per Page"}},"title":"list_signalsArguments","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_business_timeline":{"post":{"operationId":"get_business_timeline","summary":"List Secretary of State change events for a business (registration, name and address changes), newest first. Use for \"Wh","description":"List Secretary of State change events for a business (registration, name and address changes), newest first. Use for \"What registration changes has this business had recently\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"business_id":{"description":"Middesk business ID (UUID) from list_businesses, for example 'b2c3d4e5-f6a7-8901-bcde-f12345678901'.","maxLength":200,"title":"Business Id","type":"string"},"start_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only events on or after this date (YYYY-MM-DD).","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only events on or before this date (YYYY-MM-DD).","title":"End Date"},"event_types":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated event types: registration.created, registration.updated, address.created, address.deleted, person.created, person.deleted, name.created, name.deleted.","title":"Event Types"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Events per page.","title":"Per Page"}},"required":["business_id"],"title":"get_business_timelineArguments","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_business_documents":{"post":{"operationId":"list_business_documents","summary":"List filings and documents retrieved for a business (articles of incorporation, good standing certificates) with type, f","description":"List filings and documents retrieved for a business (articles of incorporation, good standing certificates) with type, file name, size and filing date. Use for \"Which formation documents does Middesk hold for this business\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"business_id":{"description":"Middesk business ID (UUID) from list_businesses, for example 'b2c3d4e5-f6a7-8901-bcde-f12345678901'.","maxLength":200,"title":"Business Id","type":"string"}},"required":["business_id"],"title":"list_business_documentsArguments","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}}}}