---
title: List topics
slug: topic-api/list-topics
docTags:
createdAt: 2024-06-10T16:49:07.009Z
---
{
"id": "WX61kpOlaPSVv0w9cp9ol",
"type": "api-oas-v2",
"data": {
"method": "GET",
"url": "https://api.catenda.com/opencde/bcf/3.0/projects/{topic-board-id}/topics",
"servers": [
{
"url": "https://api.catenda.com/opencde/bcf/3.0/projects/{topic-board-id}/topics"
}
],
"name": "List topics",
"description": "List topics.
\nFilter, search, sort, skip and limit using OData.
\nNot all properties are included in the response by default, make use of the OData select feature to adjust the response fields.
\nNullable fields without a value may not be included in the response.
",
"contentType": "application/json",
"request": {
"pathParameters": [
{
"kind": "required",
"name": "topic-board-id",
"type": "string",
"example": "e18a2d10-1595-4e52-a941-22d43bf8d7ad",
"description": "Id of the topic board"
}
],
"headerParameters": [],
"queryParameters": [
{
"kind": "optional",
"name": "includeAuthorization",
"type": "boolean",
"description": "Include authorization field in response"
},
{
"kind": "optional",
"name": "$filter",
"type": "string",
"description": "Filter topics with OData"
},
{
"kind": "optional",
"name": "$search",
"type": "string",
"description": "Search topic title and description"
},
{
"kind": "optional",
"name": "$orderby",
"type": "string",
"description": "Sort topics with OData"
},
{
"kind": "optional",
"name": "$select",
"type": "string",
"description": "Limit topic fields with OData"
},
{
"kind": "optional",
"name": "$top",
"type": "string",
"description": "Number of topics in result (page size). Default 100, max 500.
"
},
{
"kind": "optional",
"name": "$skip",
"type": "string",
"description": "Position of topic cursor. Example: With $top value of 50, set $skip to 50 to retrieve page 2, to 100 for page 3, etc...
"
}
],
"bodyDataParameters": [],
"formDataParameters": [],
"oAuthParameters": [
{
"id": "Bearer",
"name": "Bearer",
"kind": "optional",
"type": "http",
"scheme": "bearer"
}
]
},
"responses": [
{
"statusCode": "200",
"description": "OK",
"jsonExample": "",
"isExpanded": true,
"schema": [
{
"kind": "optional",
"type": "array",
"description": "",
"customType": "topic[]",
"schema": [
{
"name": "guid",
"kind": "optional",
"type": "string",
"description": "Represented as compacted UUID using 32 hexadecimal characters",
"example": "18d0273d-e15c-4924-97b3-6f47b233eebe"
},
{
"name": "server_assigned_id",
"kind": "optional",
"type": "string",
"description": "Human readable identifier unique to this topic board",
"example": "23"
},
{
"name": "topic_type",
"kind": "optional",
"type": "string",
"description": "Name of topic type",
"example": "Info"
},
{
"name": "topic_status",
"kind": "optional",
"type": "string",
"description": "Name of topic status",
"example": "Open"
},
{
"name": "title",
"kind": "optional",
"type": "string",
"description": "Title of topic",
"example": "Topic 1"
},
{
"name": "labels",
"kind": "optional",
"type": "array",
"description": "List of topic labels",
"example": "[\"Electrical\",\"Basement\"]",
"itemType": "string",
"customType": "string[]",
"itemExample": "",
"itemDefault": ""
},
{
"name": "creation_date",
"kind": "optional",
"type": "string",
"description": "Topic creation date",
"example": "2024-05-08T11:28:35.317+0000"
},
{
"name": "creation_author",
"kind": "optional",
"type": "string",
"description": "Topic creation author",
"example": "john@doe.com"
},
{
"name": "modified_date",
"kind": "optional",
"type": "string",
"description": "Topic last modified date",
"example": "2024-05-08T14:29:41.199+0000"
},
{
"name": "modified_author",
"kind": "optional",
"type": "string",
"description": "Topic last modified author",
"example": "john@doe.com"
},
{
"name": "assigned_to",
"kind": "optional",
"type": "string",
"description": "Topic assigned to user",
"example": "john@doe.com"
},
{
"name": "stage",
"kind": "optional",
"type": "string",
"description": "Topic milestone",
"example": "Phase one"
},
{
"name": "description",
"kind": "optional",
"type": "string",
"description": "Topic description",
"example": "The topic description"
},
{
"name": "due_date",
"kind": "optional",
"type": "string",
"description": "Topic due date",
"example": "2024-05-02T10:00:00.000+0000"
},
{
"name": "authorization",
"kind": "optional",
"type": "object",
"description": "Local variations from the global authorization defaults for this resource",
"example": "",
"schema": [
{
"name": "topic_actions",
"kind": "optional",
"type": "array",
"description": "List of topic actions",
"example": "[\"createComment\",\"createViewpoint\",\"update\",\"delete\",\"updateRelatedTopics\",\"updateDocumentReferences\"]",
"itemType": "string",
"customType": "string[]",
"itemExample": "",
"itemDefault": ""
},
{
"name": "topic_status",
"kind": "optional",
"type": "array",
"description": "List of topic board status names",
"example": "[\"Open\",\"Closed\"]",
"itemType": "string",
"customType": "string[]",
"itemExample": "",
"itemDefault": ""
}
]
},
{
"name": "bimsync_issue_number",
"kind": "optional",
"type": "integer",
"description": "Unique auto incremented number assigned when a new topic is created",
"example": 23
},
{
"name": "bimsync_creation_author",
"kind": "optional",
"type": "object",
"description": "Topic created by Catenda user",
"example": "",
"schema": [
{
"name": "user",
"kind": "optional",
"type": "object",
"description": "",
"modelRef": "#/components/schemas/user-ref",
"customType": "user-ref",
"schema": [
{
"name": "ref",
"kind": "optional",
"type": "string",
"description": "Id of the user",
"example": "524809076a694255b989d236517a55da"
},
{
"name": "email",
"kind": "optional",
"type": "string",
"description": "Email of the user",
"example": "john@doe.com"
},
{
"name": "name",
"kind": "optional",
"type": "string",
"description": "Name of the user",
"example": "John Doe"
}
]
},
{
"name": "importedBy",
"kind": "optional",
"type": "object",
"description": "",
"modelRef": "#/components/schemas/user-ref",
"customType": "user-ref",
"schema": [
{
"name": "ref",
"kind": "optional",
"type": "string",
"description": "Id of the user",
"example": "524809076a694255b989d236517a55da"
},
{
"name": "email",
"kind": "optional",
"type": "string",
"description": "Email of the user",
"example": "john@doe.com"
},
{
"name": "name",
"kind": "optional",
"type": "string",
"description": "Name of the user",
"example": "John Doe"
}
]
}
]
},
{
"name": "bimsync_viewpoints",
"kind": "optional",
"type": "array",
"description": "List of topic viewpoints",
"example": "",
"itemType": "object",
"customType": "object[]",
"schema": [
{
"name": "guid",
"kind": "optional",
"type": "string",
"description": "Represented as compacted UUID using 32 hexadecimal characters",
"example": "52959166-dbd2-44eb-81bb-74f955f30e0f"
},
{
"name": "hasSnapshot",
"kind": "optional",
"type": "boolean",
"description": "Whether viewpoint has any snapshot",
"example": true
}
]
},
{
"name": "bimsync_points",
"kind": "optional",
"type": "array",
"description": "List of topic points",
"example": "",
"itemType": "object",
"customType": "object[]",
"schema": [
{
"name": "x",
"kind": "optional",
"type": "number",
"description": "X coordinate of the point",
"example": 100
},
{
"name": "y",
"kind": "optional",
"type": "number",
"description": "Y coordinate of the point",
"example": 100
},
{
"name": "z",
"kind": "optional",
"type": "number",
"description": "Z coordinate of the point",
"example": 100
},
{
"name": "models",
"kind": "optional",
"type": "array",
"description": "List of models",
"example": "",
"itemType": "object",
"customType": "object[]",
"schema": [
{
"name": "modelRef",
"kind": "optional",
"type": "string",
"description": "Id of the model",
"example": "11a9bb2984ee4a999875c4cd9560f319"
},
{
"name": "revisionRef",
"kind": "optional",
"type": "string",
"description": "Id of the model revision",
"example": "eed6ae36-5fe0-4f1f-89da-fba8efcf8b97"
},
{
"name": "ref",
"kind": "optional",
"type": "string",
"description": "A reference for this model revision relation",
"example": "827f4b14-af0c-44e5-90ce-4e58fa79d7b3"
}
]
},
{
"name": "id",
"kind": "optional",
"type": "string",
"description": "Id of the point",
"example": "a08af3d4-edca-49ed-adf7-107a4a481188"
}
]
},
{
"name": "bimsync_requester",
"kind": "optional",
"type": "object",
"description": "Topic requested by Catenda user",
"example": "",
"schema": [
{
"name": "user",
"kind": "optional",
"type": "object",
"description": "",
"modelRef": "#/components/schemas/user-ref",
"customType": "user-ref",
"schema": [
{
"name": "ref",
"kind": "optional",
"type": "string",
"description": "Id of the user",
"example": "524809076a694255b989d236517a55da"
},
{
"name": "email",
"kind": "optional",
"type": "string",
"description": "Email of the user",
"example": "john@doe.com"
},
{
"name": "name",
"kind": "optional",
"type": "string",
"description": "Name of the user",
"example": "John Doe"
}
]
},
{
"name": "team",
"kind": "optional",
"type": "object",
"description": "",
"modelRef": "#/components/schemas/user-ref",
"customType": "user-ref",
"schema": [
{
"name": "ref",
"kind": "optional",
"type": "string",
"description": "Id of the user",
"example": "524809076a694255b989d236517a55da"
},
{
"name": "email",
"kind": "optional",
"type": "string",
"description": "Email of the user",
"example": "john@doe.com"
},
{
"name": "name",
"kind": "optional",
"type": "string",
"description": "Name of the user",
"example": "John Doe"
}
]
}
]
},
{
"name": "bimsync_document_references",
"kind": "optional",
"type": "array",
"description": "List of document references",
"example": "",
"itemType": "object",
"customType": "object[]",
"schema": [
{
"name": "guid",
"kind": "optional",
"type": "string",
"description": "Id of the document reference",
"example": "86962ff9-b5fe-4537-996f-8dc15461422c"
},
{
"name": "document_guid",
"kind": "optional",
"type": "string",
"description": "Id of the document",
"example": "a8644754-b646-4f67-a767-a1fef44a51c9"
}
]
},
{
"name": "bimsync_comments_size",
"kind": "optional",
"type": "integer",
"description": "Count of topic comments",
"example": 3
},
{
"name": "bimsync_assigned_to",
"kind": "optional",
"type": "object",
"description": "Topic assigned to Catenda user",
"example": "",
"schema": [
{
"name": "user",
"kind": "optional",
"type": "object",
"description": "",
"modelRef": "#/components/schemas/user-ref",
"customType": "user-ref",
"schema": [
{
"name": "ref",
"kind": "optional",
"type": "string",
"description": "Id of the user",
"example": "524809076a694255b989d236517a55da"
},
{
"name": "email",
"kind": "optional",
"type": "string",
"description": "Email of the user",
"example": "john@doe.com"
},
{
"name": "name",
"kind": "optional",
"type": "string",
"description": "Name of the user",
"example": "John Doe"
}
]
},
{
"name": "team",
"kind": "optional",
"type": "object",
"description": "",
"modelRef": "#/components/schemas/user-ref",
"customType": "user-ref",
"schema": [
{
"name": "ref",
"kind": "optional",
"type": "string",
"description": "Id of the user",
"example": "524809076a694255b989d236517a55da"
},
{
"name": "email",
"kind": "optional",
"type": "string",
"description": "Email of the user",
"example": "john@doe.com"
},
{
"name": "name",
"kind": "optional",
"type": "string",
"description": "Name of the user",
"example": "John Doe"
}
]
}
]
},
{
"name": "bimsync_labels",
"kind": "optional",
"type": "array",
"description": "List of topic labels",
"modelRef": "#/components/schemas/label",
"customType": "label[]",
"schema": [
{
"name": "id",
"kind": "optional",
"type": "string",
"description": "Id of the label",
"example": "397t0ccc8f74619096c738de15dc6512"
},
{
"name": "name",
"kind": "optional",
"type": "string",
"description": "Name of the label",
"example": "Label 1"
},
{
"name": "color",
"kind": "optional",
"type": "string",
"description": "Valid RGB hexadecimal color of the label",
"example": "#6aa84f"
},
{
"name": "group",
"kind": "optional",
"type": "object",
"description": "",
"modelRef": "#/components/schemas/label-group",
"customType": "label-group",
"schema": [
{
"name": "id",
"kind": "optional",
"type": "string",
"description": "Id of the label group",
"example": "357t0ccc8f74719096c734de18fc6512"
},
{
"name": "name",
"kind": "optional",
"type": "string",
"description": "Name of the label group",
"example": "Group name"
}
]
},
{
"name": "deleted",
"kind": "optional",
"type": "boolean",
"description": "Soft deletion state of the label",
"example": false
}
]
},
{
"name": "bimsync_custom_fields",
"kind": "optional",
"type": "array",
"description": "List of topic custom fields",
"modelRef": "#/components/schemas/custom-field",
"customType": "custom-field[]",
"schema": [
{
"name": "id",
"kind": "optional",
"type": "string",
"description": "Id of the custom field, represented as compacted UUID using 32 hexadecimal characters.",
"example": "324409076a694255b589d236517a55da"
},
{
"name": "name",
"kind": "optional",
"type": "string",
"description": "The name of the custom field.",
"example": "Custom field name"
},
{
"name": "description",
"kind": "optional",
"type": "string",
"description": "Description of the custom field.",
"example": "Custom field description"
},
{
"name": "type",
"kind": "optional",
"type": "string",
"description": "Type of the custom field. Valid values are \"text\", \"integer\", \"double\", \"enumeration\" or \"date\".",
"example": "text"
},
{
"name": "createdAt",
"kind": "optional",
"type": "string",
"description": "The date and time the custom field was created in ISO 8601 format.",
"example": "2023-03-06T11:52:45.000Z"
},
{
"name": "createdBy",
"kind": "optional",
"type": "string",
"description": "Id of the user that created the custom field.",
"example": "624809076a694255b989d236517a55da"
},
{
"name": "archived",
"kind": "optional",
"type": "boolean",
"description": "Whether the custom field is archived.",
"example": false
},
{
"name": "dropdownItems",
"kind": "optional",
"type": "array",
"description": "List of dropdown items for custom fields of type enumeration. Value is null for other custom field types.",
"example": "",
"itemType": "object",
"customType": "object[]",
"schema": [
{
"name": "id",
"kind": "optional",
"type": "string",
"description": "Id of the custom field, represented as compacted UUID using 32 hexadecimal characters.",
"example": ""
},
{
"name": "name",
"kind": "optional",
"type": "string",
"description": "Name of the dropdown item",
"example": "Dropdown item 1"
},
{
"name": "code",
"kind": "optional",
"type": "string",
"description": "The code of the enumeration item, value is unique for a custom field.",
"example": "Item name"
},
{
"name": "disabled",
"kind": "optional",
"type": "boolean",
"description": "Whether the enumeration item is disabled.",
"example": false
}
]
}
]
}
],
"modelRef": "#/components/schemas/topic",
"isExpanded": true
}
]
}
],
"hasXCodeSamples": false,
"examples": {
"languages": [
{
"id": "u6kWzhJfyHD--Yif8jinN",
"language": "curl",
"label": "cURL",
"code": "curl --request GET \\\n --url https://api.catenda.com/opencde/bcf/3.0/projects/{topic-board-id}/topics \\\n --header 'accept: application/json'"
},
{
"id": "iyoQcZq4bmslJa1_UtCtd",
"language": "javascript",
"label": "javascript",
"code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\n\nvar requestOptions = {\n method: 'GET',\n headers: myHeaders,\n redirect: 'follow'\n};\n\nfetch(\"https://api.catenda.com/opencde/bcf/3.0/projects/{topic-board-id}/topics\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));"
},
{
"id": "Sd5lBZkHM5lCtzk_d_XAI",
"language": "ruby",
"label": "Ruby",
"code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api.catenda.com/opencde/bcf/3.0/projects/{topic-board-id}/topics\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Get.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\n\nresponse = https.request(request)\nputs response.read_body\n"
},
{
"id": "7RK4mZJPGszGohFMJ3_6J",
"language": "python",
"label": "Python",
"code": "import requests\nimport json\n\nurl = \"https://api.catenda.com/opencde/bcf/3.0/projects/{topic-board-id}/topics\"\n\npayload = {}\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json'\n}\n\nresponse = requests.request(\"GET\", url, headers=headers, data=payload)\n\nprint(response.text)\n"
}
],
"selectedLanguageId": "u6kWzhJfyHD--Yif8jinN"
},
"results": {
"languages": [
{
"id": "response-0-200",
"language": "200",
"code": "// OK\n[\n {\n \"guid\": \"18d0273d-e15c-4924-97b3-6f47b233eebe\",\n \"server_assigned_id\": \"23\",\n \"topic_type\": \"Info\",\n \"topic_status\": \"Open\",\n \"title\": \"Topic 1\",\n \"labels\": [\n \"\"\n ],\n \"creation_date\": \"2024-05-08T11:28:35.317+0000\",\n \"creation_author\": \"john@doe.com\",\n \"modified_date\": \"2024-05-08T14:29:41.199+0000\",\n \"modified_author\": \"john@doe.com\",\n \"assigned_to\": \"john@doe.com\",\n \"stage\": \"Phase one\",\n \"description\": \"The topic description\",\n \"due_date\": \"2024-05-02T10:00:00.000+0000\",\n \"authorization\": {\n \"topic_actions\": [\n \"\"\n ],\n \"topic_status\": [\n \"\"\n ]\n },\n \"bimsync_issue_number\": 23,\n \"bimsync_creation_author\": {\n \"user\": {\n \"ref\": \"524809076a694255b989d236517a55da\",\n \"email\": \"john@doe.com\",\n \"name\": \"John Doe\"\n },\n \"importedBy\": {\n \"ref\": \"524809076a694255b989d236517a55da\",\n \"email\": \"john@doe.com\",\n \"name\": \"John Doe\"\n }\n },\n \"bimsync_viewpoints\": [\n {\n \"guid\": \"52959166-dbd2-44eb-81bb-74f955f30e0f\",\n \"hasSnapshot\": true\n }\n ],\n \"bimsync_points\": [\n {\n \"x\": 100,\n \"y\": 100,\n \"z\": 100,\n \"models\": [\n {\n \"modelRef\": \"11a9bb2984ee4a999875c4cd9560f319\",\n \"revisionRef\": \"eed6ae36-5fe0-4f1f-89da-fba8efcf8b97\",\n \"ref\": \"827f4b14-af0c-44e5-90ce-4e58fa79d7b3\"\n }\n ],\n \"id\": \"a08af3d4-edca-49ed-adf7-107a4a481188\"\n }\n ],\n \"bimsync_requester\": {\n \"user\": {\n \"ref\": \"524809076a694255b989d236517a55da\",\n \"email\": \"john@doe.com\",\n \"name\": \"John Doe\"\n },\n \"team\": {\n \"ref\": \"524809076a694255b989d236517a55da\",\n \"email\": \"john@doe.com\",\n \"name\": \"John Doe\"\n }\n },\n \"bimsync_document_references\": [\n {\n \"guid\": \"86962ff9-b5fe-4537-996f-8dc15461422c\",\n \"document_guid\": \"a8644754-b646-4f67-a767-a1fef44a51c9\"\n }\n ],\n \"bimsync_comments_size\": 3,\n \"bimsync_assigned_to\": {\n \"user\": {\n \"ref\": \"524809076a694255b989d236517a55da\",\n \"email\": \"john@doe.com\",\n \"name\": \"John Doe\"\n },\n \"team\": {\n \"ref\": \"524809076a694255b989d236517a55da\",\n \"email\": \"john@doe.com\",\n \"name\": \"John Doe\"\n }\n },\n \"bimsync_labels\": [\n {\n \"id\": \"397t0ccc8f74619096c738de15dc6512\",\n \"name\": \"Label 1\",\n \"color\": \"#6aa84f\",\n \"group\": {\n \"id\": \"357t0ccc8f74719096c734de18fc6512\",\n \"name\": \"Group name\"\n },\n \"deleted\": false\n }\n ],\n \"bimsync_custom_fields\": [\n {\n \"id\": \"324409076a694255b589d236517a55da\",\n \"name\": \"Custom field name\",\n \"description\": \"Custom field description\",\n \"type\": \"text\",\n \"createdAt\": \"2023-03-06T11:52:45.000Z\",\n \"createdBy\": \"624809076a694255b989d236517a55da\",\n \"archived\": false,\n \"dropdownItems\": [\n {\n \"id\": \"\",\n \"name\": \"Dropdown item 1\",\n \"code\": \"Item name\",\n \"disabled\": false\n }\n ]\n }\n ]\n }\n]"
}
],
"selectedLanguageId": "response-0-200"
}
},
"children": [
{
"text": ""
}
]
}