Returns every canned-response category in the authenticated organization, resolved for the requested locale and ordered by sort position.

GET/api/canned-responses/categories

Returns every canned-response category in the authenticated organization, resolved for the requested locale and ordered by sort position. The response includes localization metadata and does not change usage counters.

Endpoint requirements

Credentials: Use either Bearer API key or X-API-Key header.
Required scope: canned-responses:read
Module: Automation & API module (automation_api)
Organization and site scope: Requests can access only resources owned by the authenticated organization. The API does not reveal whether an identifier belongs to another organization or site.
Retry behavior: Safe read: You can safely retry this read-only request after a transport failure. It does not change resource state.

Query Parameters

locale?string

Query parameter. BCP 47 locale or language tag used for localized content.

Response Body

`application/json`

{
  "data": [
    {
      "id": "b8ec53aa-0ca2-49bb-b8f6-7458ab50260c",
      "orgId": "8ea0b557-d794-41ce-b86e-44f4780da2b5",
      "key": "billing",
      "sortOrder": 10,
      "name": "Billing",
      "locale": "en",
      "fallbackUsed": false,
      "responseCount": 1,
      "translations": [
        {
          "id": "5ed35c91-5633-4745-8f00-317104590fa8",
          "locale": "en",
          "status": "published",
          "sourceLocale": null,
          "machineTranslatedAt": null,
          "reviewedAt": null,
          "reviewedBy": null,
          "name": "Billing",
          "createdAt": "2026-08-03T18:00:00.000Z",
          "updatedAt": "2026-08-03T18:00:00.000Z"
        }
      ],
      "createdAt": "2026-08-03T18:00:00.000Z",
      "updatedAt": "2026-08-03T18:00:00.000Z"
    }
  ]
}

{
  "error": {
    "code": "string",
    "message": "string",
    "fields": {
      "property1": "string",
      "property2": "string"
    },
    "details": {},
    "correlationId": "string"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication is required.",
    "correlationId": "req_01K0MANAGEMENT401"
  }
}

{
  "error": {
    "code": "INTEGRATION_MODULE_REQUIRED",
    "message": "The automation API module is required.",
    "details": {
      "module": "automation_api",
      "feature": "public_api"
    },
    "correlationId": "req_01K0MANAGEMENT402"
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "message": "The caller lacks the required role or API-key scope.",
    "correlationId": "req_01K0MANAGEMENT403"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "fields": {
      "property1": "string",
      "property2": "string"
    },
    "details": {},
    "correlationId": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "fields": {
      "property1": "string",
      "property2": "string"
    },
    "details": {},
    "correlationId": "string"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request payload is invalid.",
    "details": {
      "field": "name"
    },
    "correlationId": "req_01K0MANAGEMENT422"
  }
}

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests.",
    "correlationId": "req_01K0MANAGEMENT429"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "fields": {
      "property1": "string",
      "property2": "string"
    },
    "details": {},
    "correlationId": "string"
  }
}

Request examples

curl

curl --request GET \
  'https://api.convor.io/api/canned-responses/categories' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer convor_sk_...'

JavaScript

const response = await fetch("https://api.convor.io/api/canned-responses/categories", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer convor_sk_..."
  },
});

const contentType = response.headers.get("content-type") ?? "";
const data = response.status === 204
  ? null
  : contentType.includes("json")
    ? await response.json()
    : contentType.startsWith("text/")
      ? await response.text()
      : await response.blob();

if (!response.ok) {
  const message = typeof data === "object" && data !== null
    && "error" in data && typeof data.error === "object"
    && data.error !== null && "message" in data.error
      ? String(data.error.message)
      : "Convor API request failed (" + response.status + ")";
  throw new Error(message);
}

console.log(data);

Was this page helpful?

List localized canned response categories

Returns every canned-response category in the authenticated organization, resolved for the requested locale and ordered by sort position.

GET/api/canned-responses/categories

Endpoint requirements

Credentials: Use either Bearer API key or X-API-Key header.
Required scope: canned-responses:read
Module: Automation & API module (automation_api)
Organization and site scope: Requests can access only resources owned by the authenticated organization. The API does not reveal whether an identifier belongs to another organization or site.
Retry behavior: Safe read: You can safely retry this read-only request after a transport failure. It does not change resource state.

Query Parameters

locale?string

Query parameter. BCP 47 locale or language tag used for localized content.

Response Body

`application/json`

{
  "data": [
    {
      "id": "b8ec53aa-0ca2-49bb-b8f6-7458ab50260c",
      "orgId": "8ea0b557-d794-41ce-b86e-44f4780da2b5",
      "key": "billing",
      "sortOrder": 10,
      "name": "Billing",
      "locale": "en",
      "fallbackUsed": false,
      "responseCount": 1,
      "translations": [
        {
          "id": "5ed35c91-5633-4745-8f00-317104590fa8",
          "locale": "en",
          "status": "published",
          "sourceLocale": null,
          "machineTranslatedAt": null,
          "reviewedAt": null,
          "reviewedBy": null,
          "name": "Billing",
          "createdAt": "2026-08-03T18:00:00.000Z",
          "updatedAt": "2026-08-03T18:00:00.000Z"
        }
      ],
      "createdAt": "2026-08-03T18:00:00.000Z",
      "updatedAt": "2026-08-03T18:00:00.000Z"
    }
  ]
}

{
  "error": {
    "code": "string",
    "message": "string",
    "fields": {
      "property1": "string",
      "property2": "string"
    },
    "details": {},
    "correlationId": "string"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication is required.",
    "correlationId": "req_01K0MANAGEMENT401"
  }
}

{
  "error": {
    "code": "INTEGRATION_MODULE_REQUIRED",
    "message": "The automation API module is required.",
    "details": {
      "module": "automation_api",
      "feature": "public_api"
    },
    "correlationId": "req_01K0MANAGEMENT402"
  }
}

{
  "error": {
    "code": "FORBIDDEN",
    "message": "The caller lacks the required role or API-key scope.",
    "correlationId": "req_01K0MANAGEMENT403"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "fields": {
      "property1": "string",
      "property2": "string"
    },
    "details": {},
    "correlationId": "string"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "fields": {
      "property1": "string",
      "property2": "string"
    },
    "details": {},
    "correlationId": "string"
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The request payload is invalid.",
    "details": {
      "field": "name"
    },
    "correlationId": "req_01K0MANAGEMENT422"
  }
}

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests.",
    "correlationId": "req_01K0MANAGEMENT429"
  }
}

{
  "error": {
    "code": "string",
    "message": "string",
    "fields": {
      "property1": "string",
      "property2": "string"
    },
    "details": {},
    "correlationId": "string"
  }
}

Request examples

curl

curl --request GET \
  'https://api.convor.io/api/canned-responses/categories' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer convor_sk_...'

JavaScript

const response = await fetch("https://api.convor.io/api/canned-responses/categories", {
  method: "GET",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer convor_sk_..."
  },
});

const contentType = response.headers.get("content-type") ?? "";
const data = response.status === 204
  ? null
  : contentType.includes("json")
    ? await response.json()
    : contentType.startsWith("text/")
      ? await response.text()
      : await response.blob();

if (!response.ok) {
  const message = typeof data === "object" && data !== null
    && "error" in data && typeof data.error === "object"
    && data.error !== null && "message" in data.error
      ? String(data.error.message)
      : "Convor API request failed (" + response.status + ")";
  throw new Error(message);
}

console.log(data);

Was this page helpful?

List localized canned response categories

Endpoint requirements

Query Parameters

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Request examples

curl

JavaScript

On this page

List localized canned response categories

Endpoint requirements

Query Parameters

Response Body

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

Request examples

curl

JavaScript

On this page

List localized canned response categories

Endpoint requirements

200application/json

400application/json

401application/json

402application/json

403application/json

404application/json

409application/json

422application/json

429application/json

500application/json

On this page

List localized canned response categories

Endpoint requirements

200application/json

400application/json

401application/json

402application/json

403application/json

404application/json

409application/json

422application/json

429application/json

500application/json

On this page

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`