VersionSelectConnect a catalog API
Use an organization-approved HTTPS API implementing the fixed VersionSelect catalog contract. This is not an arbitrary REST mapping tool.
- Choose Backend API in settings.
- Enter an API Base URL, such as
https://catalog.example.com. A path prefix is allowed; query strings, fragments, and embedded credentials are rejected. - Enter a Bearer Token issued by the catalog service—not an Atlassian account API token—and limit it to required catalog reads.
- Select Save configuration and approve the origin in Atlassian's outbound-access dialog. If approval is denied, the new configuration is not saved.
- Select Test connection. VersionSelect makes a direct, uncached request for the first service-list item so the test checks the saved credential as well as reachability and the response contract. Then verify service and version selection in a test work item.
Transport rules
Requests run from Forge rather than the user's browser. Every catalog request uses HTTPS GET, Accept: application/json, and Authorization: Bearer <catalog-token>. HTTPS redirects are rejected. Responses must be valid JSON no larger than 1 MiB, and requests use an eight-second abort timer.
Endpoints
| Endpoint | Query parameters | Successful response |
|---|---|---|
/catalog/v1/services | query, page, pageSize. Test connection uses query=, page=1, and pageSize=1. | Paginated services with name and optional group; an empty catalog is valid. |
/catalog/v1/versions | group, service, query, page, pageSize, sort=createdAt, order=desc | Paginated versions with name and optional createdAt |
A separate health endpoint is optional and is not used by VersionSelect to test credentials.
Example responses
{"items":[{"group":"Payments","name":"payments-api"}],
"page":1,"pageSize":50,"total":1,"totalPages":1}{"items":[{"name":"2.4.1","createdAt":"2026-09-01T00:00:00Z"}],
"page":1,"pageSize":10,"total":1,"totalPages":1}Pagination, sorting, and identity
Pages start at 1 and page sizes are at most 50. Return accurate totals; an empty list may use total: 0 and totalPages: 0. Sort versions newest first before pagination. URL parameters are encoded by the app. An empty group identifies an ungrouped service. Service identity derives from group and name; version identity derives from its name within the service.
Caching and configuration changes
Service responses are cached for approximately five minutes and versions for two minutes. Search uses only the current catalog. Changing the URL changes subsequent searches. Switching sources does not remove the saved token; use Delete token and revoke the credential at the source when needed.
Data sent to the catalog API
The API receives search text, pagination, service names/groups, and the credential. VersionSelect does not add Jira account identity, work item bodies, comments, or attachments. The API operator controls its access logs, retention, and processing locations. Do not place personal information in catalog names or search text.