{"openapi":"3.1.0","info":{"title":"Swarmia (BYOK) API","version":"0.1.0","description":"Swarmia (BYOK) lets an AI assistant read your own Swarmia data through the Swarmia API with a key you supply (Swarmia API token (scope for the reports you read)). Read-only: 5 tools (get_code_metrics, get_dora_metrics, get_ai_assistant_adoption, get_custom_report, list_teams). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it is only...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-swarmia.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-swarmia/docs"},"termsOfService":"https://connectorbay.com/byok-swarmia/terms"},"servers":[{"url":"https://byok-swarmia.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-swarmia/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/get_code_metrics":{"post":{"operationId":"get_code_metrics","summary":"Pull request metrics per team over a period: cycle time, review rate, time to first review (seconds), merge time, merged","description":"Pull request metrics per team over a period: cycle time, review rate, time to first review (seconds), merge time, merged count, contributors. One row per team plus a summary row. Use for \"What was our PR cycle time per team in September in Swarmia\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"revision":{"description":"Report revision to serve: a number such as 2, or 'latest'.","maxLength":10,"title":"Revision","type":"string"},"timeframe_start":{"description":"Start of the period, inclusive (YYYY-MM-DD).","maxLength":30,"title":"Timeframe Start","type":"string"},"timeframe_end":{"description":"End of the period, inclusive (YYYY-MM-DD).","maxLength":30,"title":"Timeframe End","type":"string"},"timezone":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"IANA timezone for date handling, for example 'Europe/Helsinki' (default: the organization's timezone).","title":"Timezone"},"team_id":{"anyOf":[{"maxLength":400,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated team UUIDs to include (use this or parent_team_id, not both; omit both for all teams).","title":"Team Id"},"parent_team_id":{"anyOf":[{"maxLength":400,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated parent team UUIDs: returns their child teams. The literal 'null' selects top-level teams.","title":"Parent Team Id"},"aggregate":{"anyOf":[{"enum":["Sum","Avg","Min","Max","P99","P95","P90","P85","P80","P75","P50"],"type":"string"},{"type":"null"}],"default":"Avg","description":"How durations are aggregated.","title":"Aggregate"},"output":{"anyOf":[{"const":"json","type":"string"},{"type":"null"}],"default":"json","description":"Response format; keep json.","title":"Output"},"exclude_weekends":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True or false overrides the organization's weekend setting for cycle and merge time.","title":"Exclude Weekends"}},"required":["revision","timeframe_start","timeframe_end"],"title":"get_code_metricsArguments","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_dora_metrics":{"post":{"operationId":"get_dora_metrics","summary":"DORA metrics over a period for the organization or per team: change lead time, release time, time to recovery (seconds),","description":"DORA metrics over a period for the organization or per team: change lead time, release time, time to recovery (seconds), change failure rate and deployment count. Use for \"What are our DORA metrics for the last month in Swarmia\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"revision":{"description":"Report revision to serve: a number such as 2, or 'latest'.","maxLength":10,"title":"Revision","type":"string"},"timeframe_start":{"description":"Start of the period, inclusive (YYYY-MM-DD).","maxLength":30,"title":"Timeframe Start","type":"string"},"timeframe_end":{"description":"End of the period, inclusive (YYYY-MM-DD).","maxLength":30,"title":"Timeframe End","type":"string"},"timezone":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"IANA timezone for date handling, for example 'Europe/Helsinki' (default: the organization's timezone).","title":"Timezone"},"team_id":{"anyOf":[{"maxLength":400,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated team UUIDs to include (use this or parent_team_id, not both; omit both for all teams).","title":"Team Id"},"parent_team_id":{"anyOf":[{"maxLength":400,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated parent team UUIDs: returns their child teams. The literal 'null' selects top-level teams.","title":"Parent Team Id"},"aggregate":{"anyOf":[{"enum":["Sum","Avg","Min","Max","P99","P95","P90","P85","P80","P75","P50"],"type":"string"},{"type":"null"}],"default":"Avg","description":"How durations are aggregated.","title":"Aggregate"},"output":{"anyOf":[{"const":"json","type":"string"},{"type":"null"}],"default":"json","description":"Response format; keep json.","title":"Output"}},"required":["revision","timeframe_start","timeframe_end"],"title":"get_dora_metricsArguments","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_ai_assistant_adoption":{"post":{"operationId":"get_ai_assistant_adoption","summary":"Counts of enabled and active AI coding assistant users and contributors in a period, per team plus a summary (user ident","description":"Counts of enabled and active AI coding assistant users and contributors in a period, per team plus a summary (user identities are not returned). Use for \"How many of our developers actively use AI coding assistants according to Swarmia\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"revision":{"description":"Report revision to serve: a number such as 2, or 'latest'.","maxLength":10,"title":"Revision","type":"string"},"timeframe_start":{"description":"Start of the period, inclusive (YYYY-MM-DD).","maxLength":30,"title":"Timeframe Start","type":"string"},"timeframe_end":{"description":"End of the period, inclusive (YYYY-MM-DD).","maxLength":30,"title":"Timeframe End","type":"string"},"timezone":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"IANA timezone for date handling, for example 'Europe/Helsinki' (default: the organization's timezone).","title":"Timezone"},"team_id":{"anyOf":[{"maxLength":400,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated team UUIDs to include (use this or parent_team_id, not both; omit both for all teams).","title":"Team Id"},"parent_team_id":{"anyOf":[{"maxLength":400,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated parent team UUIDs: returns their child teams. The literal 'null' selects top-level teams.","title":"Parent Team Id"},"output":{"anyOf":[{"const":"json","type":"string"},{"type":"null"}],"default":"json","description":"Response format; keep json.","title":"Output"},"active_contributors_only":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"True counts only members who opened a pull request in the period.","title":"Active Contributors Only"},"ai_assistants":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated AI assistants to include (default: all).","title":"Ai Assistants"}},"required":["revision","timeframe_start","timeframe_end"],"title":"get_ai_assistant_adoptionArguments","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_report":{"post":{"operationId":"get_custom_report","summary":"Run a custom report saved in the Swarmia Explore page, by its UUID (shown as activeReport in the app URL). Rows depend o","description":"Run a custom report saved in the Swarmia Explore page, by its UUID (shown as activeReport in the app URL). Rows depend on the report; paged by limit and offset. Use for \"Run my saved Swarmia report\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"report_id":{"description":"UUID of the saved custom report.","maxLength":200,"title":"Report Id","type":"string"},"output":{"anyOf":[{"const":"json","type":"string"},{"type":"null"}],"default":"json","description":"Response format; keep json.","title":"Output"},"limit":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"Rows per page (1 to 1000).","title":"Limit"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Rows to skip (0 to 100000).","title":"Offset"},"include_total":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True adds the total row count to the pagination block.","title":"Include Total"},"timeframe_start":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Override the report's timeframe start (YYYY-MM-DD); send together with timeframe_end.","title":"Timeframe Start"},"timeframe_end":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Override the report's timeframe end (YYYY-MM-DD).","title":"Timeframe End"},"timezone":{"anyOf":[{"maxLength":60,"type":"string"},{"type":"null"}],"default":null,"description":"IANA timezone for date handling, for example 'Europe/Helsinki' (default: the organization's timezone).","title":"Timezone"}},"required":["report_id"],"title":"get_custom_reportArguments","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_teams":{"post":{"operationId":"list_teams","summary":"List the organization's teams with ids, parent links, external ids and the Jira or Linear keys they own (members and adm","description":"List the organization's teams with ids, parent links, external ids and the Jira or Linear keys they own (members and admin emails are left out). Use for \"Which teams are defined in Swarmia\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_teamsArguments","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}}}}