Skip to content
Sursa Developers

GET/v1/catalog/services

List services in the catalog

list_catalog_services

Returns entries of the global catalog of external services (SaaS and vendors): a case-insensitive substring search in the name, group or website domain, a category filter and pagination. The total count for the filter is in the X-Total-Count header. The catalog is shared by all organizations and is available to any signed-in user. Its data ships with Sursa and is updated with each release (the version is in GET /v1/catalog/categories and in the version field of each entry's icon_url).

Authentication

Send an API key in the Authorization header: Authorization: Bearer <key>.

Query parameters

  • qstring | null

    Substring of the name, group or website domain (case-insensitive).

    length ≤ 200

  • categorystring | null

    Category slug (GET /v1/catalog/categories).

  • offsetinteger

    Default: 0≥ 0

  • limitinteger

    Default: 50≥ 1, ≤ 500

  • cursorstring

    Cursor of the next page from X-Next-Cursor or next_cursor of the previous response with the same filters; it carries the page size. Together with offset: 422 validation.failed; a cursor of another list, other filters or a malformed one: 400 api.cursor_invalid.

    length ≤ 512

Header parameters

  • X-View-Asstring

    For API keys with the admin role only. Makes the request as the data profile <profile>[:viewer|verifier|editor], for example employee:viewer. The installation key cannot use this header (403).

Cookie parameters

  • kb_view_asstring

    Cookie of the “View as” mode for a session. POST /auth/view-as sets it and DELETE /auth/view-as clears it.

Responses

200OK

Response headers

  • Link

    Address of the next page, <…>; rel="next". No header means this is the last page.

  • X-Next-Cursor

    Cursor of the next page for the cursor parameter. No header means this is the last page.

  • X-Total-Count

    Total number of records that match the filter, regardless of limit and offset.

  • RateLimit-Policy

    Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.

  • RateLimit

    What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).

  • X-RateLimit-Remaining

    Requests left under the strictest limit.

  • X-RateLimit-Reset

    Seconds until the strictest limit resets.

application/json

array of CatalogService
  • categorystringrequired

    Category slug (GET /v1/catalog/categories).

  • description_enstring | nullrequired

    Short description in English. null if there is no description.

  • domainstring | nullrequired

    Website domain without www.. null if there is no website.

  • group_namestring | nullrequired

    Group (vendor) if the service belongs to a product family, for example Atlassian; otherwise null.

  • iconbooleanrequired

    Whether an icon ships with Sursa.

  • icon_urlstring | nullrequired

    Icon URL (/v1/catalog/services/{service_id}/icon?v=… or an external address configured by the installation). null if there is no icon.

  • idstring (uuid)required
  • namestringrequired
  • slugstringrequired
  • websitestring | nullrequired

    Website URL (https://…) or null.

401No credentials were sent (neither a session cookie nor an API key), or the key was not found.

Response headers

  • RateLimit-Policy

    Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.

  • RateLimit

    What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).

  • X-RateLimit-Remaining

    Requests left under the strictest limit.

  • X-RateLimit-Reset

    Seconds until the strictest limit resets.

application/json

Object: Error

403The action is not allowed: the role is insufficient, there is no access to the collection or card, the request runs in “View as” mode, or the organization is suspended or deleted (`detail` is an object with `code: org_suspended | org_deleted`).

Response headers

  • RateLimit-Policy

    Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.

  • RateLimit

    What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).

  • X-RateLimit-Remaining

    Requests left under the strictest limit.

  • X-RateLimit-Reset

    Seconds until the strictest limit resets.

application/json

Object: Error

422Validation error: the body or parameters do not match the schema (`detail` is a list of validation errors), or a parameter value is out of range (`detail` is a message).

Response headers

  • RateLimit-Policy

    Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.

  • RateLimit

    What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).

  • X-RateLimit-Remaining

    Requests left under the strictest limit.

  • X-RateLimit-Reset

    Seconds until the strictest limit resets.

application/json

Object: Error

429Too many requests (`api.rate_limited`), the organization's quota for the minute, day or month is used up (`api.quota_exceeded`; `error.details` holds `quota`, `limit` and `reset_at`), the organization's limit is reached, or the answer service is busy (`answers.engine_busy`). Wait for the time in the `Retry-After` header.

Response headers

  • Retry-After

    Number of seconds to wait before you retry the request.

  • RateLimit-Policy

    Limits in effect, in the format of the IETF draft draft-ietf-httpapi-ratelimit-headers: comma-separated items "<name>";q=<quota>;w=<window in seconds>. key is the request rate of the API key (the quota is the burst, the window is the time to refill it fully; for a session it is user, without credentials ip); minute, day and month are the organization's quotas for the calendar minute, day and month in UTC.

  • RateLimit

    What is left of each limit in RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Limit of the strictest entry in RateLimit-Policy (the one with the fewest requests left).

  • X-RateLimit-Remaining

    Requests left under the strictest limit.

  • X-RateLimit-Reset

    Seconds until the strictest limit resets.

application/json

Object: Error

Error codes

Codes this endpoint can return in error.code, besides the general codes of every request.

Rate limits

Responses carry the RateLimit and RateLimit-Policy headers and the earlier X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. A 429 response has Retry-After in seconds: wait and retry.

← catalog · API reference