FORMAT: 1A HOST: https://api.oncollabim.com/ # Collabim API Base URL for all API requests is https://api.oncollabim.com. Always use https (secure) instead of http. Authorization \ HTTP header is used for user authentication. User API key could be found in your profile settings in application after logging in. Use query parameter page for results pagination (example: https://api.oncollabim.com/activities?page=\). Use parameter format to get results in csv (example: https://api.oncollabim.com/projects?format=csv). List of Collabim supported search engines is available here. ### POSTMAN Collection We have already prepared POSTMAN collection for our API, the actual version could be downloaded here. The ENV settings (params) could be downloaded here. ## Project info [/projects/{id}] To get attributes for single project use end-point /projects/{projectId} + Parameters + id: `1` (number, required) - project ID ### Get project info [GET] + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "data": { "id": 1, "name": "url.cz", "webSiteUrl": "http://www.url.cz/", "active": 1, "tags": [ "tag1" ] } } ## Project list [/projects{?nameLike,active,page,itemsPerPage}] This end point /projects displays list of all your projects. ### Get project list [GET] + Parameters + nameLike: `project name` (string, optional) - Displays projects whose name contains string specified in filter. + active: `0` (boolean, optional) - Displays active (1) or archived (0) projects. + page: `1` (number, optional) - Displays 10 projects per page. Default value is 1. + itemsPerPage: `20` (number, optional) - Change number of results per page. Default is 20. + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "data": [ { "id": 1, "name": "web1.cz", "webSiteUrl": "http://web1.cz/", "active": 1 }, { "id": 2, "name": "web2.cz", "webSiteUrl": "http://web2.cz/", "active": 1 }, { "id": 3, "name": "web3.cz", "webSiteUrl": "http://web3.cz/", "active": 1 } ] } ## Project widget [/projects/{id}/widget/{type}] End-point /projects/{projectId}/widget/{widgetType} returns Collabim widget as a HTML. + Parameters + id: `1` (number, required) - project ID + type: `fullWidget` (enum[string], required) - widget type + Members: + fullWidget ### Get project widget [GET] + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (text/html) ## Project widget as JSON [/projects/{id}/widget/{type}/json] If you would like to get Collabim widget as json use /projects/{projectId}/widget/{widgetType}/json. + Parameters + id: `1` (number, required) - project ID + type: `fullWidget` (enum[string], required) - widget type + Members: + fullWidget ### Get project widget as JSON [GET] + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "keywordsStats": [ { "keyword": "keyword 1", "positions": [ { "searchEngine": "Google CZ", "position": 10, "positionDifference": -1, "added": "2018-02-25" }, { "searchEngine": "Seznam.cz", "position": 255, "positionDifference": 0, "added": "2018-02-25" }, { "searchEngine": "Google CZ - obrázky", "position": 255, "positionDifference": 0, "added": "2018-02-25" } ] }, { "keyword": "keyword 2", "positions": [ { "searchEngine": "Google CZ", "position": 10, "positionDifference": -1, "added": "2018-02-25" }, { "searchEngine": "Seznam.cz", "position": 255, "positionDifference": 0, "added": "2018-02-25" }, { "searchEngine": "Google CZ - obrázky", "position": 255, "positionDifference": 0, "added": "2018-02-25" } ] }, ], "topCompetitors": [ { "url": "http://www.url1.cz" }, { "url": "http://www.url2.cz" }, { "url": "http://url3.cz" }, { "url": "http://www.url4.cz" }, { "url": "http://www.url5.cz" } ], "backlinkVerificationList": [ { "resultName": "NOT found", "pageWithLinkUrl": "http://cs.wikipedia.org/wiki/term1" }, { "resultName": "NOT found", "pageWithLinkUrl": "http://www.idnes.cz/example2" } ], "backlinkProblemsCount": 26, "projectStats": [ { "searchEngineName": "Google CZ", "ci": -0.0448313, "added": "2018-02-25" }, { "searchEngineName": "Seznam.cz", "ci": 0.021863, "added": "2018-02-25" }, { "searchEngineName": "Google CZ - obrázky", "ci": 0.163015, "added": "2018-02-25" } ] } ## Activity list [/activities{?projectId,typeId,stateId,createdById,categoryId,noCategory,addedOnFrom,addedOnTo,urlLike,webId,page,itemsPerPage}] GET method for /activities returns list of activities up to limit 7000. ### Get Activity list [GET] + Parameters + projectId: `1` (number, optional) - Displays activities assigned to specified project. + typeId: `1` (number, optional) - Displays activities of a specified type only (backlinks, articles etc.) + stateId: `1` (number, optional) - Displays activities in a specified state only (completed, queued, postponed etc.) + createdById: `1` (number, optional) - Displays activities created by a specified person only. + categoryId: `1` (number, optional) - Displays activities assigned to a specified category only. This filter must NOT be combined with noCategory filter. + noCategory: `1` (boolean, optional) - Displays activities that are not given any category. This filter must NOT be combined with categoryId filter. + addedOnFrom: `2020-01-01` (date, optional) - Displays activities that were created after given date. (YYYY-MM-DD) + addedOnTo: `2020-01-01` (date, optional) - Displays activities that were created before given date. (YYYY-MM-DD) + urlLike: `http://www.url.cz/` (string, optional)' - Display activities whose web URL or page with link URL contains specified string. + webId: `1` (number, optional) - Displays activities assigned to a specified website only. + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "data": [ { "id": 1, "stateId": 1, "typeId": 1, "anchorText": null, "webId": 1, "webSiteUrl": "http://www.url.cz/", "webNote": null, "webPrice": 1500, "pageWithLinkUrl": "http://www.url.cz/", "targetPage": "", "categoryId": null, "addedOn": "2020-01-01", "projectId": 1, "stateName": "completed", "typeName": "Backlink", "categoryName": null, "projectName": "http://www.url.cz/", "activityNote": null } ] } ## Single activity [/activities/{id}] GET method on /activities/{activityId} displays attributes of activity with {activityId}. PUT method updates attributes of activity with this id and DELETE method deletes this activity. You can update these attributes: projectId (integer), typeId (integer), stateId (integer), categoryId (integer), createdById (integer), webId (integer), note (string), pageWithLinkUrl (string) and webSiteUrl (string). **stateId** enum: * 1 queued * 3 contacted * 4 completed * 5 no deal * 6 uninteresting * 7 postponed * 9 not responding **typeId** enum: * 1 Other * 2 Backlink * 3 Directory registration * 5 Article * 7 Banner * 11 Discussion post + Parameters + id: `1` (number, required) - activity ID ### Get activity [GET] + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "data": { "id": 1, "stateId": 1, "anchorText": "anchor-text", "typeId": 1, "webId": 1, "webSiteUrl": "http://www.url.cz/", "webNote": null, "webPrice": 1500, "pageWithLinkUrl": "http://www.url.cz/", "categoryId": null, "addedOn": "2020-01-01", "projectId": 1, "stateName": "completed", "typeName": "Backlink", "categoryName": null, "projectName": "http://www.url.cz/", "activityNote": null } } ### Update activity [PUT] + Request + Body { "stateId": 1, "anchorText": "", "typeId": 2, "webId": 348482, "webSiteUrl": "https://www.bydlo.cz", "webNote": "test 22222 - new", "webPrice": {}, "pageWithLinkUrl": "http://bydlo.cz", "targetPage": "https://www.bydlo.cz/", "categoryId": {}, "addedOn": "2020-08-13", "projectId": 93111, "stateName": "queued", "typeName": "Backlink", "categoryName": {}, "projectName": "alza.cz", "activityNote": "" } + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) ### Delete activity [DELETE] + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) ## Keyword list [/keywords{?projectId,keyword,keywordLike,tags,targetPageId,starred,page,itemsPerPage}] /keywords displays list of your keywords. Also see the list of supported search engines. ### Get keyword list [GET] + Parameters + projectId: `1` (number, optional) - Displays keywords assigned to specified project. + keyword: `my keyword` (string, optional) - Displays keyword with specified text only (exact match). + keywordLike: `my keyword` (string, optional) - Displays keywords whose name contains specified string. + tags: `my tag` (string, optional) - Displays keywords assigned with at least one of given tags. + targetPageId: `1` (number, optional) - Displays keywords assigned to specified target page. + starred: `0` (boolean, optional) - Displays keywords marked with a star (1) or keywords without star (0) + page: `1` (number, optional) - Displays 10 projects per page. Default value is 1. + itemsPerPage: `10` (number, optional) - Change number of results per page. Default is 10. + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "data": [ { "id": 1, "keyword": "my keyword", "searchesGoogleCurrent": 1, "searchesGoogleYear": 1, "searchesSeznamCurrent": 1, "searchesSeznamYear": 1, "svGoogle": 1, "svGoogleLocal": 1, "svSeznam": 1, "positions": [ { "searchEngineId": 1, "position": 1, "positionDifference": 1, "snippetTitle": "My website", "snippetBody": "Description of my website", "targetPageUrl": "http://www.url.cz/", "totalNumberOfResults": 10, "searchEngineName": "Google CZ" } ], "starred": 0, "tags": [ "my tag", "my another tag" ], "targetPageId": null, "visits": null, "bounceRate": null, "pagesPerVisit": null, "transactions": null, "ecommerceConversionRate": null, "impressions": null, "clicks": null, "ctr": null, "avgPositionGwt": null, "note": null, "targetPageUrl": "http://www.url.cz/", "targetPageTitle": "My website" } ] } ## Keyword positions [/keyword-positions{?projectId,projectKeywordIds,lastXDays,tags,getXDays}] /keyword-positions displays history of positions for given keywords. Limit of project keywords dynamically depends on day interval by the following calculation: 7000 / day interval (lastXDays). Also see the list of supported search engines. ### By last X days [GET] + Parameters + projectId: `1` (number, required) - Select positions for given project only + lastXDays: `30` (number, required) - Return position to given days back + projectKeywordIds: `1,2` (integer list, optional) - Return keywords with given IDs only (You have to fill atleast on of projectKeywordIds or tags parameter) + tags: `my tag` (string, optional) - Displays keywords assigned with at least one of given tags (You have to fill atleast on of projectKeywordIds or tags parameter) + getXDays: `15` (number, optional) - Return position for only given X days + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "data": [ { "projectKeywordId": 1, "text": "my keyword", "positions": [ { "searchEngineId": 1, "position": 1, "date":"2020-01-01", "searchEngineName": "Google CZ" }, { "searchEngineId": 2, "position": 2, "date":"2020-01-01", "searchEngineName": "Google CZ" }, { "searchEngineId": 3, "position": 3, "date":"2020-01-01", "searchEngineName": "Google CZ" } ] }, { "projectKeywordId": 2, "text":"my another keyword", "positions": [ { "searchEngineId": 1, "position": 1, "date":"2020-01-01", "searchEngineName": "Google CZ" }, { "searchEngineId": 2, "position": 2, "date":"2020-01-01", "searchEngineName": "Google CZ" }, { "searchEngineId": 3, "position": 3, "date":"2020-01-01", "searchEngineName": "Google CZ" } ] } ] } ## Keyword positions [/keyword-positions{?projectId,projectKeywordIds,from,to,tags,getXDays}] /keyword-positions displays history of positions for given keywords. Limit of project keywords dynamically depends on day interval by the following calculation: 7000 / day interval (difference between from and to). Also see the list of supported search engines. ### By interval - from, to [GET] + Parameters + projectId: `1` (number, required) - Select positions for given project only + projectKeywordIds: `1,2` (integer list, optional) - Return keywords with given IDs only (You have to fill atleast on of projectKeywordIds or tags parameter) + tags: `my tag` (string, optional) - Displays keywords assigned with at least one of given tags (You have to fill atleast on of projectKeywordIds or tags parameter) + from: `2020-01-01` (date, required) - Return positions from given date only (YYYY-MM-DD) + to: `2020-01-01` (date, required) - Return positions from given date only (YYYY-MM-DD) + getXDays: `15` (number, optional) - Return position for only given X days + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "data": [ { "projectKeywordId": 1, "text": "my keyword", "positions": [ { "searchEngineId": 1, "position": 1, "date":"2020-01-01", "searchEngineName": "Google CZ" }, { "searchEngineId": 2, "position": 2, "date":"2020-01-01", "searchEngineName": "Google CZ" }, { "searchEngineId": 3, "position": 3, "date":"2020-01-01", "searchEngineName": "Google CZ" } ] }, { "projectKeywordId": 2, "text":"my another keyword", "positions": [ { "searchEngineId": 1, "position": 1, "date":"2020-01-01", "searchEngineName": "Google CZ" }, { "searchEngineId": 2, "position": 2, "date":"2020-01-01", "searchEngineName": "Google CZ" }, { "searchEngineId": 3, "position": 3, "date":"2020-01-01", "searchEngineName": "Google CZ" } ] } ] } ## First and last keyword position [/keyword-positions{?projectId,projectKeywordIds,lastXDays,tags,onlyFirstAndLastPositionStats,getXDays}] Returns only first and last keyword position. See also Keyword positions. ### By last X days [GET] + Parameters + projectId: `1` (number, required) - Select positions for given project only + projectKeywordIds: `1,2` (integer list, optional) - Return keywords with given IDs only (You have to fill atleast on of projectKeywordIds or tags parameter) + lastXDays: `30` (number, required) - Return position to given days back + tags: `my tag` (string, optional) - Displays keywords assigned with at least one of given tags (You have to fill atleast on of projectKeywordIds or tags parameter) + onlyFirstAndLastPositionStats: `1` (boolean, required) - Display only first and last keyword position + getXDays: `15` (number, optional) - Return position for only given X days + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "data": [ { "projectKeywordId": 1, "text": "my keyword", "positions": [ { "searchEngineId": 1, "position": 1, "date":"2020-01-01", "searchEngineName": "Google CZ" }, { "searchEngineId": 2, "position": 2, "date":"2020-01-01", "searchEngineName": "Google CZ" }, { "searchEngineId": 3, "position": 3, "date":"2020-01-01", "searchEngineName": "Google CZ" } ] }, { "projectKeywordId": 2, "text":"my another keyword", "positions": [ { "searchEngineId": 1, "position": 1, "date":"2020-01-01", "searchEngineName": "Google CZ" }, { "searchEngineId": 2, "position": 2, "date":"2020-01-01", "searchEngineName": "Google CZ" }, { "searchEngineId": 3, "position": 3, "date":"2020-01-01", "searchEngineName": "Google CZ" } ] } ] } ## First and last keyword position [/keyword-positions{?projectId,projectKeywordIds,from,to,tags,onlyFirstAndLastPositionStats,getXDays}] Returns only first and last keyword position. See also Keyword positions. ### By interval - from, to [GET] + Parameters + projectId: `1` (number, required) - Select positions for given project only + projectKeywordIds: `1,2` (integer list, optional) - Return keywords with given IDs only (You have to fill atleast on of projectKeywordIds or tags parameter) + from: `2020-01-01` (date, required) - Return positions from given date only (YYYY-MM-DD) + to: `2020-01-01` (date, required) - Return positions from given date only (YYYY-MM-DD) + tags: `my tag` (string, optional) - Displays keywords assigned with at least one of given tags (You have to fill atleast on of projectKeywordIds or tags parameter) + onlyFirstAndLastPositionStats: `1` (boolean, required) - Display only first and last keyword position + getXDays: `15` (number, optional) - Return position for only given X days + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "data": [ { "projectKeywordId": 1, "text": "my keyword", "positions": [ { "searchEngineId": 1, "position": 1, "date":"2020-01-01", "searchEngineName": "Google CZ" }, { "searchEngineId": 2, "position": 2, "date":"2020-01-01", "searchEngineName": "Google CZ" }, { "searchEngineId": 3, "position": 3, "date":"2020-01-01", "searchEngineName": "Google CZ" } ] }, { "projectKeywordId": 2, "text":"my another keyword", "positions": [ { "searchEngineId": 1, "position": 1, "date":"2020-01-01", "searchEngineName": "Google CZ" }, { "searchEngineId": 2, "position": 2, "date":"2020-01-01", "searchEngineName": "Google CZ" }, { "searchEngineId": 3, "position": 3, "date":"2020-01-01", "searchEngineName": "Google CZ" } ] } ] } ## Keyword aggregated positions [/aggregated-keywords-positions{?projectId,lastXDays,tags,getXDays}] /aggregated-keyword-positions displays aggregated positions for all keywords in given project. Also see the list of supported search engines. ### By last X days [GET] + Parameters + projectId: `1` (number, required) - Select positions for given project only + lastXDays: `30` (number, required) - Return position to given days back + tags: `my tag` (string, optional) - Displays keywords assigned with at least one of given tags + getXDays: `15` (number, optional) - Return position for only given X days + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "data": [ { "projectKeywordId": 1, "text": "my keyword", "positions": [ { "searchEngineId": 1, "position": 1, "date":"2020-01-01", "searchEngineName": "Google CZ" }, { "searchEngineId": 2, "position": 2, "date":"2020-01-01", "searchEngineName": "Google CZ" }, { "searchEngineId": 3, "position": 3, "date":"2020-01-01", "searchEngineName": "Google CZ" } ] }, { "projectKeywordId": 2, "text":"my another keyword", "positions": [ { "searchEngineId": 1, "position": 1, "date":"2020-01-01", "searchEngineName": "Google CZ" }, { "searchEngineId": 2, "position": 2, "date":"2020-01-01", "searchEngineName": "Google CZ" }, { "searchEngineId": 3, "position": 3, "date":"2020-01-01", "searchEngineName": "Google CZ" } ] } ] } ## Keyword aggregated positions [/aggregated-keywords-positions{?projectId,from,to,tags,getXDays}] /aggregated-keyword-positions displays aggregated positions for all keywords in given project. Also see the list of supported search engines. ### By interval - from, to [GET] + Parameters + projectId: `1` (number, required) - Select positions for given project only + from: `2020-01-01` (date, required) - Return positions from given date only (YYYY-MM-DD) + to: `2020-01-01` (date, required) - Return positions from given date only (YYYY-MM-DD) + tags: `my tag` (string, optional) - Displays keywords assigned with at least one of given tags + getXDays: `15` (number, optional) - Return position for only given X days + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "data": [ { "projectKeywordId": 1, "text": "my keyword", "positions": [ { "searchEngineId": 1, "position": 1, "date":"2020-01-01", "searchEngineName": "Google CZ" }, { "searchEngineId": 2, "position": 2, "date":"2020-01-01", "searchEngineName": "Google CZ" }, { "searchEngineId": 3, "position": 3, "date":"2020-01-01", "searchEngineName": "Google CZ" } ] }, { "projectKeywordId": 2, "text":"my another keyword", "positions": [ { "searchEngineId": 1, "position": 1, "date":"2020-01-01", "searchEngineName": "Google CZ" }, { "searchEngineId": 2, "position": 2, "date":"2020-01-01", "searchEngineName": "Google CZ" }, { "searchEngineId": 3, "position": 3, "date":"2020-01-01", "searchEngineName": "Google CZ" } ] } ] } ## Position distribution [/position-distribution{?projectId,tagName,lastXDays,getXDays}] /position-distribution returns position distribution for given project. ### By last X days [GET] + Parameters + projectId: `1` (number, required) - Select position distribution for given project + lastXDays: `30` (number, required) - Return position distribution for given days back + getXDays: `15` (number, optional) - Return position distribution for only given X days + tagName: `tag` (string, optional) - Select position distribution for given tag only + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "data": [ { "projectId": "1", "tagId": "1", "addedOn": "2020-01-01", "searchEngineId": "1", "countTop3": "1", "count4to10": "1", "count11to20": "1", "count21plus": "1", "projectName": "My Project", "searchEngineName": "Google CZ", "tagName": "tag" } ] } ## Position distribution [/position-distribution{?projectId,tagName,from,to,getXDays}] /position-distribution returns position distribution for given project. ### By interval - from, to [GET] + Parameters + projectId: `1` (number, required) - Select position distribution for given project + from: `2020-01-01` (date, required) - Return position distribution from given date only (YYYY-MM-DD) + to: `2020-01-30` (date, required) - Return position distribution to given date only (YYYY-MM-DD) + getXDays: `15` (number, optional) - Return position distribution for only given X days + tagName: `tag` (string, optional) - Select position distribution for given tag only + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "data": [ { "projectId": "1", "tagId": "1", "addedOn": "2020-01-01", "searchEngineId": "1", "countTop3": "1", "count4to10": "1", "count11to20": "1", "count21plus": "1", "projectName": "My Project", "searchEngineName": "Google CZ", "tagName": "tag" } ] } ## MARKET dominator [/market-dominator{?projectId,tagName,lastXDays,getXDays}] /market-dominator returns market dominator values for given project. ### By last X days [GET] + Parameters + projectId: `1` (number, required) - Select position distribution for given project + lastXDays: `30` (number, required) - Return position distribution for given days back + getXDays: `15` (number, optional) - Return position distribution for only given X days + tagName: `tag` (string, optional) - Select position distribution for given tag only + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "data": [ { "addedOn": "2022-10-18", "searchEngineId": 1, "searchEngineName": "Google CZ", "searchesTotal": 257335, "theoreticalVisitsTop3": 823, "theoreticalVisits4to10": 500, "theoreticalVisits11to20": 784, "theoreticalVisits21plus": 413 } ] } ## MARKET dominator [/market-dominator{?projectId,tagName,from,to,getXDays}] /market-dominator returns market dominator values for given project. ### By interval - from, to [GET] + Parameters + projectId: `1` (number, required) - Select position distribution for given project + from: `2020-01-01` (date, required) - Return position distribution from given date only (YYYY-MM-DD) + to: `2020-01-30` (date, required) - Return position distribution to given date only (YYYY-MM-DD) + getXDays: `15` (number, optional) - Return position distribution for only given X days + tagName: `tag` (string, optional) - Select position distribution for given tag only + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "data": [ { "addedOn": "2022-10-18", "searchEngineId": 1, "searchEngineName": "Google CZ", "searchesTotal": 257335, "theoreticalVisitsTop3": 823, "theoreticalVisits4to10": 500, "theoreticalVisits11to20": 784, "theoreticalVisits21plus": 413 } ] } ## Indexed pages [/indexed-pages{?projectId,searchEngineId,lastXDays}] /indexed-pages displays indexed pages for given project. Also see the list of supported search engines. You can get indexed pages for date interval (from - to) or for lastXDays. ### By last X days [GET] + Parameters + projectId: `1` (number, required) - Show indexed pages stats for given project only + searchEngineId: `1` (number, optional) - Show indexed pages stats for given search engine + lastXDays: `30` (number, required) - Return position to given days back + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "data": [ { "date": "2020-01-01", "searchEngineId": 1, "indexedPages": 3, "searchEngineName": "Google CZ" }, { "date":"2020-01-01", "searchEngineId": 2, "indexedPages": 3, "searchEngineName": "Google CZ" }, { "date":"2020-01-01", "searchEngineId": 3, "indexedPages": 3, "searchEngineName": "Google CZ" } ] } ## Indexed pages [/indexed-pages{?projectId,searchEngineId,from,to}] /indexed-pages displays indexed pages for given project. Also see the list of supported search engines. You can get indexed pages for date interval (from - to) or for lastXDays. ### By interval - from, to [GET] + Parameters + projectId: `1` (number, required) - Show indexed pages stats for given project only + searchEngineId: `1` (number, optional) - Show indexed pages stats for given search engine + from: `2020-01-01` (date, required) - Show indexed pages stats from given date only (YYYY-MM-DD) + to: `2020-01-01` (date, required) - Show indexed pages stats to given date only (YYYY-MM-DD) + Request + Headers Accept: aplication/collabim+json Authorization: + Response 200 (application/json) + Body { "data": [ { "date": "2020-01-01", "searchEngineId": 1, "indexedPages": 3, "searchEngineName": "Google CZ" }, { "date":"2020-01-01", "searchEngineId": 2, "indexedPages": 3, "searchEngineName": "Google CZ" }, { "date":"2020-01-01", "searchEngineId": 3, "indexedPages": 3, "searchEngineName": "Google CZ" } ] } ## Market share [/market-share{?projectId,searchEngineId,tagName}] This endpoint /market-share returns data from market share graph. Also see the list of supported search engines. ### Get market share [GET] + Parameters + projectId: `1` (number, required) - Show market share data for given project + searchEngineId: `1` (number, required) - Show market share data for given search engine + tagName: `my-tag` (string, optional) - Show market share data for given tag name only + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "data": [ { "name": "e-shop.cz", "data": [ { "date": "2020-01-01", "count": 1, "tagId": 1, "tagName": "tag" } ] } ] } ## Market share history [/market-share{?projectId,searchEngineId,lastXDays,getXDays,tagName}] Use /market-share endpoint with parameters lastXDays to get market share history in given date interval. ### By last X days [GET] + Parameters + projectId: `1` (number, required) - Show market share data for given project + searchEngineId: `1` (number, required) - Show market share data for given search engine + lastXDays: `30` (number, required) - Return market share data for given days back + getXDays: `15` (number, optional) - Return market share data for only given X days + tagName: `my-tag` (string, optional) - Show market share data for given tag name only + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "data": [ { "name": "e-shop.cz", "data": [ { "date": "2020-01-01", "count": 1, "tagId": 1, "tagName": "tag" } ] } ] } ## Market share history [/market-share{?projectId,searchEngineId,from,to,getXDays,tagName}] Use /market-share endpoint with parameters from and to to get market share history in given date interval. ### By interval - from, to [GET] + Parameters + projectId: `1` (number, required) - Show market share data for given project + searchEngineId: `1` (number, required) - Show market share data for given search engine + from: `2020-01-01` (date, required) - Return market share data from given date only (YYYY-MM-DD) + to: `2020-01-30` (date, required) - Return market share data to given date only (YYYY-MM-DD) + getXDays: `15` (number, optional) - Return market share data for only given X days + tagName: `my-tag` (string, optional) - Show market share data for given tag name only + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "data": [ { "name": "e-shop.cz", "data": [ { "date": "2020-01-01", "count": 1, "tagId": 1, "tagName": "tag" } ] } ] } ## New account [/accounts/new] You can create new Collabim acount using API - for cooperation with affil partners only. If you desire to use this endpoint, please contact us. Locale enum: * cs_CZ - Czech * sk_SK - Slovak * ru_RU - Russian * en_US - English (default) Available country codes: https://bit.ly/2rfsKth ### Registration [POST] + Attributes + planNumber: `1` (number, required) - Our internal plan ID. Contact us for plan informations. + locale: `cs_CZ` (string, required) - Sets language for created account. Available locale codes: cs_CZ, sk_SK, ru_RU, en_US. + email: `email@example.com` (string, required) - Email to be registered as owner of an account. + password: `u76Cdsofm8xy` (string, required) - Password is optional. Password reset will be send if needed. + siteAddress: `e-shop.cz` (string, required) - Website that belongs to client. Eshop URL for example. Could be empty. + keywords: `shirt,hat,leggings` (string, required) - Keywords that will be automatically added to project after account creation. Could be empty. + promoCode: `partner` (string, required) - Promo code of the partner, contact us for more informations. + approvedTermsDate: `2020-12-10` (string, required) - Approved terms of use date. Terms can be found here: https://www.collabim.cz/podminky-sluzby.html or in English here: https://www.collabim.com/terms-of-use.html + country: `CZ` (string, optional) - Country of account. If not specified we will _try_ to get it from locale. Available country codes can be found here: https://bit.ly/2rfsKth. + phone: `+420783927092` (string, optional) - Phone number of account owner. + Request + Headers Accept: application/collabim+json Authorization: + Request (application/json) { "api_registration_form": { "planNumber": "2", "locale": "cs_CZ", "email": "email@example.com", "password": "u76Cdsofm8xy", "siteAddress": "e-shop.cz", "keywords": "jedna,dva,tri", "promoCode": "partner", "approvedTermsDate": "2020-12-10", "country": "CZ", "phone": "+420123456789" } } + Response 200 (application/json) + Body { "siteAddress": "z345_cz", "projectId": 50, "userKey": "f7fcc9d173432e7a0c90fca1860ea4932c68b558" } + Response 400 (application/json) + Body { "email": "This value should not be blank." } + Response 401 (application/json) + Body { "message": "Unathorized access, please contact our support." } ## User key [/user-key] For cooperation with affil partners only. If you desire to use this endpoint, please contact us. Available country codes: https://bit.ly/2rfsKth ### Retrieve user API key [POST] + Request + Headers Accept: application/collabim+json Content-Type: application/json Authorization: + Body { "api_login_form": { "siteAddress": "test", "email": "owner@example.com", "password": "heslo123" } } + Response 200 (application/json) + Body { "userKey": "6af88353248c4884a0576bc05bdf2341419d0110" } ## Holy grail stats [/holy-grail-stats/{domain}] + Parameters + domain: `collabim.cz` (string, required) - domain for statistics ### Get holy grail stats for domain [GET] + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "domainStats": { "allKeywordsCount": 1000, "statsPerSearchEngine": { "Seznam.cz": 450, "Google CZ": 350, "Google SK": 200 } } } ## Holy Grail for AIO Stats [/holy-grail-aio-stats/{domain}] Endpoint returns All-in-One (AIO) Holy Grail statistics for a specified domain, focusing on publicly available data. + Parameters + domain: `collabim.cz` (string, required) - doména pre štatistiky ### Get Holy Grail AIO stats [GET] + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "domainStats": { "allKeywordsCount": 850 } } ## Holy Grail Organic Data [/holy-grail-api-data/{domain}{?format}] The endpoint returns Holy Grail organic data in JSON or CSV format. Large datasets are returned in multiple pages. Call the endpoint once and then keep requesting `meta.next_url` until it becomes `null`. The first page creates a Holy Grail one-time analysis in your account history and deducts credits based on total row count. Next pages do not deduct credits again. + Parameters + domain: `collabim.cz` (string, required) - doména pre dáta ### Get Holy Grail organic data [GET] + Parameters + format: `json` (enum[string], required) - Formát výstupu (json alebo csv) + Members: + json + csv + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "data": [ { "keyword": "seo nástroje", "words_count": 2, "domain": "collabim.cz", "path": "/seo-nastroje", "date_added": "2024-01-15", "search_engine": "Google CZ", "position": 3, "search_volume": 5400, "actual_theoretical_visits": 123.45, "visits_on_5_positions_up": 180.12, "visits_on_10_positions_up": 240.34, "visits_on_1st_position": 320.56 } ], "meta": { "total": 12709, "has_more": true, "next_url": "/holy-grail-data/collabim.cz?format=json&limit=5000&offset=5000&otaId=12345&charge=0" } } ## Holy Grail for AIO Data [/holy-grail-aio-data/{domain}{?format}] The endpoint returns Google AI Overview (AIO) Holy Grail data in JSON or CSV format. Large datasets are returned in multiple pages. Call the endpoint once and then keep requesting `meta.next_url` until it becomes `null`. The first page creates a Holy Grail one-time analysis in your account history and deducts credits based on total row count. Next pages do not deduct credits again. + Parameters + domain: `collabim.cz` (string, required) - doména pre dáta ### Get Holy Grail AIO data [GET] + Parameters + format: `json` (enum[string], required) - Formát výstupu (json alebo csv) + Members: + json + csv + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "data": [ { "keyword": "seo nástroje", "domain": "collabim.cz", "search_engine": "Google CZ", "date": "2024-01-15", "aio_mainbox_position": 3, "aio_sidebar_position": 1, "aio_top_results": 0, "path": "/seo-nastroje", "google_search_volume": 5400, "words_count": 15 } ], "meta": { "total": 12345, "has_more": true, "next_url": "/holy-grail-aio-data/collabim.cz?format=json&limit=5000&offset=5000&otaId=12345&charge=0" } } ## Google AI Competitors [/google-ai-overviews/{domain}/competitors] Returns competitor-level Google AI Overview data for the specified project and search engine. ### Get Google AI Competitors [GET /google-ai-overviews/{domain}/competitors{?projectId,searchEngineId,format}] + Parameters + domain: `collabim.cz` (string, required) - Doména pro analýzu + projectId: `123` (number, required) - Project ID + searchEngineId: `1` (number, required) - Search engine ID + format: `json` (enum[string], optional) - Output format + Members: + json + csv + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "data": { "competitors_aio": [ { "keyword": "seo tools", "search_volume": 5400, "project_link_position": 1, "project_result_position": 3, "project_total_result_positions": 10, "project_recommended_position": 0, "project_position": 3.5, "target_pane": "main", "competitor_123_link_position": 2, "competitor_123_result_position": 4, "competitor_123_total_result_positions": 8, "competitor_123_recommended_position": 1, "competitor_123_position": 4.2, "competitor_123_path": "/seo-tools", "wildcard_competitor1.cz_link_position": 3, "wildcard_competitor1.cz_result_position": 5, "wildcard_competitor1.cz_total_result_positions": 12, "wildcard_competitor1.cz_recommended_position": 0, "wildcard_competitor1.cz_position": 5.5, "wildcard_competitor1.cz_path": "/seo" } ] } } ## Google AI Market Share [/google-ai-overviews/{domain}/market-share] Returns Google AI Market Share time-series data for the specified project and search engine. ### Get Google AI Market Share [GET /google-ai-overviews/{domain}/market-share{?projectId,searchEngineId,from,to,lastXDays,getXDays,tagName,format}] + Parameters + domain: `collabim.cz` (string, required) - Doména pro analýzu + projectId: `123` (number, required) - Project ID + searchEngineId: `1` (number, required) - Search engine ID + from: `2024-01-01` (string, optional) - Start date for historical data (YYYY-MM-DD) + to: `2024-01-31` (string, optional) - End date for historical data (YYYY-MM-DD) + lastXDays: `30` (number, optional) - Number of days back for historical data + getXDays: `15` (number, optional) - Number of days to return + tagName: `priority` (string, optional) - Tag name for filtering + format: `json` (enum[string], optional) - Output format + Members: + json + csv + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "data": { "aio_market_share": { "project": "collabim.cz", "search_engine": "Google CZ", "data": [ { "date": "2024-01-15", "visibility_index": 45.8, "market_share_percentage": 15.3, "top3_keywords": 75, "top10_keywords": 250 } ] } } } ## HEUREKA categories [/category-downloader/heureka-tree] ### Get XLSX with actual HEUREKA categories [GET] + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (binary file) ## One time analyses keyword measuring [/ota/keyword-measuring] This is a special service, available only for business partners. If you would like to use this, feel free to contact us for pricing. Available Google GEO location codes: https://goo.gl/t7UAww Available Search engines: https://goo.gl/mKTAZB Priority enum: * 0 - standard queue, till 24 hours * 1 - priority queue, ASAP Result type: * json - json with results * html - pure html from search engine ### Send keyword batch for measuring [POST] + Request + Headers Accept: application/collabim+json Content-Type: application/json Authorization: + Body { "keyword_measuring_form": { "searchEngine": 1, "geoId": 123, "priority": 0, "desiredResultType": "html", "keywords": [ "keyword 1", "keyword 2", "keyword 3" ] } } + Response 200 (application/json) + Body { "batchId": "123456" } + Response 401 (application/json) + Body { "message": "Unathorized access, please contact our support." } ## One time analyses keyword measuring - results [/ota/keyword-measuring/status] ### Get keyword batch results [POST] + Request + Headers Accept: application/collabim+json Content-Type: application/json Authorization: + Body { "keyword_measuring_status_form": { "batchId": 123456 } } + Response 200 (application/json) + Body { "batchId": 123456, "searchEngine": 1, "geoId": 123, "priority": 0, "desiredResultType": "html", "keywords": [ "keyword 1": "url1", "keyword 2": "url2", "keyword 3": "url3" ] } + Response 418 (application/json) + Body { "message": "Keyword batch not ready yet." } + Response 401 (application/json) + Body { "message": "Unathorized access, please contact our support." } ## Prompt detail [/projects/{projectId}/prompts/{promptId}] GET metoda zobrazí podrobné informace o konkrétním promptu včetně jeho štítků a dat z posledního měření. PATCH metoda slouží k částečné aktualizaci textu, intervalu měření nebo štítků u tohoto promptu. Můžete aktualizovat tyto atributy: text (string), interval (integer) a tags (array of strings). **interval** enum: * 1 - denní měření * 7 - týdenní měření * 14 - čtrnáctidenní měření + Parameters + projectId: 123 (number, required) - ID projektu + promptId: 456 (number, required) - ID promptu ### Get prompt details [GET] + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "data": { "text": "Text promptu", "tags": [ "seo", "marketing" ], "interval": 7, "latestMeasurement": { "id": 789, "measured_at": "2026-06-19 12:00:00" }, "fanOutQueries": [ "fan out query 1", "fan out query 2" ], "sources": [ "https://example.com/source1" ], "sentimentRationale": "Zdůvodnění výsledného sentimentu." } } + Response 404 (application/json) + Body { "message": "Project not found." } + Response 410 (application/json) + Body { "message": "Prompt not found." } ### Patch prompt details [PATCH] + Request (application/json) + Headers Accept: application/collabim+json Authorization: + Body { "text": "Nový text promptu", "interval": 7, "tags": [ "seo", "marketing" ] } + Response 200 (text/plain) Prompt was edited successfully. + Response 400 (text/plain) Interval must 1, 7 or 14. + Response 404 (application/json) + Body { "message": "Project not found." } + Response 404 (application/json) + Body { "message": "Prompt not found." } + Response 409 (application/json) + Body { "message": "The prompt is now being measured." } ## Content Suggestions [/content-suggestions/start] Use this endpoint to start one-time Content Suggestions analysis. After starting the analysis, store the returned `otaId` and poll the status endpoint until `excelUrl` is not `null`. #### Validation notes + Field `url` is required. + Backend automatically adds protocol to `url` if missing. + Field `url` must be a valid domain or URL. + If provided, `projectId` must belong to one of the current user's active projects. + The analysis requires Holy Grail keyword data for the given domain or URL path. ### Start Content Suggestions [POST] + Attributes + url: `https://www.example.com/category/` (string, required) - Domain or URL for which content suggestions should be generated. + projectId: `123` (number, optional) - Target project ID. + Request + Headers Accept: application/collabim+json Content-Type: application/json Authorization: + Body { "url": "https://www.example.com/category/", "projectId": 123 } + Response 200 (application/json) + Body { "otaId": 12345 } + Response 400 (application/json) + Body { "errors": [ "Missing \"url\"" ] } ## Content Suggestions Status [/content-suggestions/status{?otaId}] Use this endpoint to check whether the Content Suggestions export is ready. If the analysis is not finished yet, `excelUrl` and `exportedAt` are `null`. ### Get Content Suggestions status [GET] + Parameters + otaId: `12345` (number, required) - One-time analysis ID returned by the start endpoint. + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "excelUrl": null, "exportedAt": null } + Response 400 (application/json) + Body { "errors": [ "Missing otaId" ] } + Response 400 (application/json) + Body { "errors": [ "Invalid OTA type" ] } + Response 403 (application/json) + Body { "errors": [ "Forbidden" ] } + Response 404 (application/json) + Body { "errors": [ "OTA not found" ] } ## Google AI Analysis [/google-ai-analysis/start] Use this endpoint to start one-time Google AI Analysis. After starting the analysis, store the returned `otaId` and poll the status endpoint until `excelUrl` is not `null`. `searchEngineIds` uses the same search engine IDs as the supported search engines documentation referenced at the beginning of this API documentation. #### Validation notes + Field `keywords` is required. + Field `searchEngineIds` is required. + Field `competitors` is required and must be a boolean. + Field `countryCode` must contain a supported country code. + If `competitors=false`, field `extractionUrl` is required. + A maximum of 4 search engines is supported. + Only Google search engines are supported for Google AI Analysis. ### Start Google AI Analysis [POST] + Attributes + keywords (array[string], required) - List of keywords to analyse. You can also send this field as a newline-separated string. + searchEngineIds (array[number], required) - Google search engine IDs used for Google AI Analysis. Minimum 1, maximum 4. + competitors: `false` (boolean, required) - Enables competitor mode. When `true`, `extractionUrl` is ignored. + extractionUrl: `https://www.example.com/` (string, optional) - URL used for extraction. Required when `competitors=false`. + countryCode: `CZ` (string, optional) - Country code used for validation of allowed search engines. If omitted, backend falls back to user default OTA country or client country. + projectId: `123` (number, optional) - Target project ID. + label: `My Google AI Analysis` (string, optional) - Custom analysis label. + Request + Headers Accept: application/collabim+json Content-Type: application/json Authorization: + Body { "keywords": [ "running shoes", "trail shoes" ], "searchEngineIds": [66], "competitors": false, "extractionUrl": "https://www.example.com/", "countryCode": "CZ", "projectId": 123, "label": "Example Google AI analysis" } + Response 200 (application/json) + Body { "otaId": 12345 } + Response 400 (application/json) + Body { "errors": [ "Missing \"searchEngineIds\"" ] } + Response 402 (application/json) + Body { "errors": [ "Payment required or setup failed" ] } ## Google AI Analysis Status [/google-ai-analysis/status{?otaId}] Use this endpoint to check whether the Google AI Analysis export is ready. If the analysis is not finished yet, `excelUrl` and `exportedAt` are `null`. ### Get Google AI Analysis status [GET] + Parameters + otaId: `12345` (number, required) - One-time analysis ID returned by the start endpoint. + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "excelUrl": null, "exportedAt": null } + Response 400 (application/json) + Body { "errors": [ "Missing otaId" ] } + Response 400 (application/json) + Body { "errors": [ "Invalid OTA type" ] } + Response 403 (application/json) + Body { "errors": [ "Forbidden" ] } + Response 404 (application/json) + Body { "errors": [ "OTA not found" ] } ## Google AI Mode Analysis [/google-ai-mode-analysis/start] Use this endpoint to start one-time Google AI Mode Analysis. Supported analysis type is `googleAi`. After starting the analysis, store the returned `otaId` and poll the status endpoint until `excelUrl` is not `null`. `googleAiSearchEngines` uses the same search engine IDs as the supported search engines documentation referenced at the beginning of this API documentation. #### Validation notes + `analyses` must contain `googleAi`. + Field `googleAiSearchEngines` is required. + Field `googleAiExtractionUrl` is required. ### Start Google AI Mode Analysis [POST] + Attributes + keywords (array[string], required) - List of keywords to analyse. You can also send this field as a newline-separated string. + analyses (array[string], required) - List of analyses to run. + Members + googleAi + googleAiSearchEngines: `66` (number, required) - Search engine ID used for Google AI Mode analysis. + googleAiExtractionUrl: `https://www.example.com/` (string, required) - URL used for Google AI Mode extraction. + countryCode: `CZ` (string, optional) - Country code used to resolve default country-specific setup. You can also use `country`. + country: `CZ` (string, optional) - Alias for `countryCode`. + label: `My Google AI Mode Analysis` (string, optional) - Custom analysis label. + projectId: `123` (number, optional) - Target project ID. + Request + Headers Accept: application/collabim+json Content-Type: application/json Authorization: + Body { "keywords": [ "running shoes", "trail shoes" ], "analyses": [ "googleAi" ], "googleAiSearchEngines": 66, "googleAiExtractionUrl": "https://www.example.com/", "countryCode": "CZ", "label": "Example Google AI Mode analysis", "projectId": 123 } + Response 200 (application/json) + Body { "otaId": 12345 } + Response 400 (application/json) + Body { "errors": [ "No keywords provided" ] } + Response 402 (application/json) + Body { "errors": [ "You don't have enough credit." ] } ## Google AI Mode Analysis Status [/google-ai-mode-analysis/status{?otaId}] Use this endpoint to check whether the Google AI Mode Analysis export is ready. If the analysis is not finished yet, `excelUrl` and `exportedAt` are `null`. ### Get Google AI Mode Analysis status [GET] + Parameters + otaId: `12345` (number, required) - One-time analysis ID returned by the start endpoint. + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "excelUrl": null, "exportedAt": null } + Response 400 (application/json) + Body { "errors": [ "Missing otaId" ] } + Response 403 (application/json) + Body { "errors": [ "Forbidden" ] } + Response 404 (application/json) + Body { "errors": [ "OTA not found" ] } ## Keyword Suggestions [/suggest-and-search-volume/start] Use this endpoint to start one-time Keyword Suggestions analysis. Before calling the start endpoint, use the info endpoint to get valid `suggesters` and `keywordTools` for the selected country. After starting the analysis, store the returned `otaId` and poll the status endpoint until `excelUrl` is not `null`. #### Validation notes + Field `keywords` is required. + At least one of `suggesters` or `keywordTools` must contain at least one valid ID. + All `suggesters` and `keywordTools` IDs must be valid for the resolved `countryCode`. + If invalid IDs are provided, the endpoint returns helper lists of valid available options for the selected country. ### Start Keyword Suggestions [POST] + Attributes + keywords (array[string], required) - List of keywords to analyse. You can also send this field as a newline-separated string. + countryCode: `CZ` (string, optional) - Country code used to resolve valid suggesters and keyword tools. If omitted, backend falls back to user default OTA country or client country. + suggesters (array[number], optional) - Suggester IDs to use for the analysis. + keywordTools (array[number], optional) - Keyword tool IDs to use for the analysis. + label: `My Keyword Suggestions` (string, optional) - Custom analysis label. + projectId: `123` (number, optional) - Target project ID. + city: `` (string, optional) - City identifier used only for Google suggesters. + Request + Headers Accept: application/collabim+json Content-Type: application/json Authorization: + Body { "keywords": [ "running shoes", "trail shoes" ], "countryCode": "CZ", "suggesters": [66], "keywordTools": [3], "label": "Example keyword suggestions", "projectId": 123, "city": "" } + Response 200 (application/json) + Body { "otaId": 12345 } + Response 400 (application/json) + Body { "errors": [ "At least one suggester or keywordTool must be selected" ] } + Response 400 (application/json) + Body { "errors": [ "Invalid countryCode XX" ] } + Response 402 (application/json) + Body { "errors": [ "Payment required or setup failed" ] } ## Keyword Suggestions Status [/suggest-and-search-volume/status{?otaId}] Use this endpoint to check whether the Keyword Suggestions export is ready. If the analysis is not finished yet, `excelUrl` and `exportedAt` are `null`. ### Get Keyword Suggestions status [GET] + Parameters + otaId: `12345` (number, required) - One-time analysis ID returned by the start endpoint. + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "excelUrl": null, "exportedAt": null } + Response 400 (application/json) + Body { "errors": [ "Missing otaId" ] } + Response 400 (application/json) + Body { "errors": [ "Invalid OTA type" ] } + Response 403 (application/json) + Body { "errors": [ "Forbidden" ] } + Response 404 (application/json) + Body { "errors": [ "OTA not found" ] } ## Keyword Suggestions Info [/suggest-and-search-volume/info{?countryCode}] Use this endpoint to get valid `suggesters` and `keywordTools` for the selected country before starting the analysis. ### Get Keyword Suggestions info [GET] + Parameters + countryCode: `CZ` (string, optional) - Country code used to resolve available suggesters and keyword tools. If omitted, backend falls back to user default OTA country or client country. + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "countryCode": "CZ", "availableSuggesters": [ { "id": 66, "name": "Google CZ" } ], "availableKeywordTools": [ { "id": 3, "name": "Bazos" } ] } + Response 400 (application/json) + Body { "errors": [ "Invalid countryCode XX" ] } ## LLM Analysis [/llm-analysis/start] Use this endpoint to start one-time LLM Analysis. After starting the analysis, store the returned `otaId` and poll the status endpoint until `excelUrl` is not `null`. Supported `llmTypes` values are `chatgpt`, `gemini` and `perplexity`. #### Validation notes + Field `keywords` is required. + Field `websiteUrl` is required. + If provided, `llmTypes` must contain only supported values. + If provided, `projectId` must exist and belong to the current client. + If provided, all `competitorProjectIds` must exist and belong to the current client. ### Start LLM Analysis [POST] + Attributes + keywords (array[string], required) - List of prompts to analyse. You can also send this field as a newline-separated string. + websiteUrl: `https://www.example.com/` (string, required) - Website URL used for analysis context. + llmTypes (array[string], optional) - LLM types to run. If omitted, backend defaults to `chatgpt`. + Members + chatgpt + gemini + perplexity + analysisName: `My LLM Analysis` (string, optional) - Custom analysis label. + projectId: `123` (number, optional) - Target project ID. + countryCode: `CZ` (string, optional) - Country code used for analysis context. Default is `CZ`. + cityId: `1000` (number, optional) - Geo/city ID used for analysis context. + includeFanOutQueries: `true` (boolean, optional) - Include fan-out queries in the result. Default is `true`. + includeProducts: `true` (boolean, optional) - Include products in the result. Default is `true`. + includeSources: `true` (boolean, optional) - Include sources in the result. Default is `true`. + includeCompetitors: `false` (boolean, optional) - Include competitors in the result. Default is `false`. + competitorProjectIds (array[number], optional) - Project IDs used to resolve competitor URLs. + customCompetitorUrls (array[string], optional) - Custom competitor URLs added to the analysis. + Request + Headers Accept: application/collabim+json Content-Type: application/json Authorization: + Body { "keywords": [ "best running shoes for beginners", "trail shoes for women" ], "websiteUrl": "https://www.example.com/", "llmTypes": [ "chatgpt", "gemini" ], "analysisName": "Example LLM analysis", "projectId": 123, "countryCode": "CZ", "cityId": 1000, "includeFanOutQueries": true, "includeProducts": true, "includeSources": true, "includeCompetitors": true, "competitorProjectIds": [456, 789], "customCompetitorUrls": [ "https://competitor1.com/", "https://competitor2.com/" ] } + Response 200 (application/json) + Body { "otaId": 12345 } + Response 400 (application/json) + Body { "errors": [ "Missing \"websiteUrl\"" ] } + Response 402 (application/json) + Body { "error": "not_enough_credits", "creditBalance": 10, "creditCost": 25 } + Response 402 (application/json) + Body { "error": "llm_limit_reached", "llm_usage": 80, "llm_limit": 100 } + Response 403 (application/json) + Body { "errors": [ "Forbidden" ] } ## LLM Analysis Status [/llm-analysis/status{?otaId}] Use this endpoint to check whether the LLM Analysis export is ready. If the analysis is not finished yet, `excelUrl` and `exportedAt` are `null`. ### Get LLM Analysis status [GET] + Parameters + otaId: `12345` (number, required) - One-time analysis ID returned by the start endpoint. + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "excelUrl": null, "exportedAt": null } + Response 400 (application/json) + Body { "errors": [ "Missing otaId" ] } + Response 400 (application/json) + Body { "errors": [ "Invalid OTA type" ] } + Response 403 (application/json) + Body { "errors": [ "Forbidden" ] } + Response 404 (application/json) + Body { "errors": [ "OTA not found" ] } ## PPC Analysis [/ppc-analysis/start] Use this endpoint to start one-time PPC Analysis. Supported analysis types are `domain` and `domains`. - `domain` returns detailed PPC ad rows for the entered keywords. Optional field `for_domain` filters results to a specific domain. - `domains` compares the provided domains list across the entered keywords. For each keyword, the output shows whether each provided domain appears in PPC results. After starting the analysis, store the returned `otaId` and poll the status endpoint until `excelUrl` is not `null`. #### Validation notes + `analyses` must contain at least one of `domain` or `domains`. + If `analyses` contains `domains`, field `domains` is required. + A maximum of 5 domains is supported for `domains` analysis. + All provided domains must be valid domain names. ### Start PPC Analysis [POST] + Attributes + keywords (array[string], required) - List of keywords to analyse. You can also send this field as a newline-separated string. + analyses (array[string], required) - List of analyses to run. + Members + domain + domains + projectId: `123` (number, optional) - Target project ID. + label: `My PPC Analysis` (string, optional) - Custom analysis label. + for_domain (array[string], optional) - Optional domain filter. You can also send a single string value. + domains (array[string], optional) - List of competitor domains for `domains` analysis. Required when `analyses` contains `domains`. Maximum 5 domains. + Request + Headers Accept: application/collabim+json Content-Type: application/json Authorization: + Body { "keywords": [ "running shoes", "trail shoes" ], "analyses": [ "domain", "domains" ], "projectId": 123, "label": "Example PPC analysis", "for_domain": [ "example.com" ], "domains": [ "competitor1.com", "competitor2.com" ] } + Response 200 (application/json) + Body { "otaId": 12345 } + Response 400 (application/json) + Body { "errors": [ "No keywords provided" ] } + Response 402 (application/json) + Body { "errors": [ "Payment required / setup failed" ] } ## PPC Analysis Status [/ppc-analysis/status{?otaId}] Use this endpoint to check whether the PPC Analysis export is ready. If the analysis is not finished yet `excelUrl` and `exportedAt` are null. ### Get PPC Analysis status [GET] + Parameters + otaId: `12345` (number, required) - One-time analysis ID returned by the start endpoint. + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "excelUrl": null, "exportedAt": null } + Response 400 (application/json) + Body { "errors": [ "Missing otaId" ] } + Response 403 (application/json) + Body { "errors": [ "Forbidden" ] } + Response 404 (application/json) + Body { "errors": [ "OTA not found" ] } ## Position and Search Volume Analysis [/keyword-analysis/position-search-volume/start] Use this endpoint to start one-time Position and Search Volume Analysis. Supported analysis types are `position`, `searchVolume` and `allInTitle`. After starting the analysis, store the returned `otaId` and poll the status endpoint until `excelUrl` is not `null`. `positionSearchEngines`, `searchVolumeSearchEngines` and `allInTitleSearchEngines` use the same search engine IDs as the supported search engines documentation referenced at the beginning of this API documentation. #### Validation notes + `analyses` must contain at least one of `position`, `searchVolume` or `allInTitle`. + If `analyses` contains `position`, field `positionSearchEngines` is required. + If `analyses` contains `position`, at least one of `positionExtractionUrl` or `serp=true` must be provided. + If `analyses` contains `searchVolume`, field `searchVolumeSearchEngines` is required. + If `analyses` contains `allInTitle`, field `allInTitleSearchEngines` is required. + If `geo` is provided as text, `country` or `countryCode` must also be provided. ### Start Position and Search Volume Analysis [POST] + Attributes + keywords (array[string], required) - List of keywords to analyse. You can also send this field as a newline-separated string. + analyses (array[string], required) - List of analyses to run. + Members + position + searchVolume + allInTitle + label: `My Analysis` (string, optional) - Custom analysis label. + projectId: `123` (number, optional) - Target project ID. + countryCode: `CZ` (string, optional) - Country code used for geo resolution and validation. You can also use `country`. + country: `CZ` (string, optional) - Alias for `countryCode`. + geo: `1234567` (string, optional) - Geo criteria ID or geo name for the selected country. If omitted, default geo for the selected country is used. + positionSearchEngines (array[number], optional) - Search engine IDs used for position analysis. + searchVolumeSearchEngines (array[number], optional) - Search engine IDs used for search volume analysis. + allInTitleSearchEngines (array[number], optional) - Search engine IDs used for AllInTitle analysis. + positionExtractionUrl: `https://www.example.com/` (string, optional) - URL used for position extraction. + serp: `false` (boolean, optional) - Enables complete SERP export for position analysis. + serpLimit: `10` (number, optional) - Maximum number of SERP results per keyword. + Request + Headers Accept: application/collabim+json Content-Type: application/json Authorization: + Body { "keywords": [ "running shoes", "trail shoes" ], "analyses": [ "position", "searchVolume", "allInTitle" ], "label": "Example keyword analysis", "projectId": 123, "countryCode": "CZ", "geo": 1000, "positionSearchEngines": [66], "searchVolumeSearchEngines": [66], "allInTitleSearchEngines": [66], "positionExtractionUrl": "https://www.example.com/", "serp": true, "serpLimit": 10 } + Response 200 (application/json) + Body { "otaId": 12345 } + Response 400 (application/json) + Body { "errors": [ "No keywords provided" ] } + Response 402 (application/json) + Body { "errors": [ "You don't have enough credit." ] } ## Position and Search Volume Analysis Status [/keyword-analysis/position-search-volume/status{?otaId}] Use this endpoint to check whether the Position and Search Volume Analysis export is ready. If the analysis is not finished yet, `excelUrl` and `exportedAt` are `null`. ### Get Position and Search Volume Analysis status [GET] + Parameters + otaId: `12345` (number, required) - One-time analysis ID returned by the start endpoint. + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "excelUrl": null, "exportedAt": null } + Response 400 (application/json) + Body { "errors": [ "Missing otaId" ] } + Response 403 (application/json) + Body { "errors": [ "Forbidden" ] } + Response 404 (application/json) + Body { "errors": [ "OTA not found" ] } ## URL Analysis [/url-analysis/start] Use this endpoint to start one-time URL Analysis. Supported analysis types are `url` and `page_analyser` After starting the analysis, store the returned `otaId` and poll the status endpoint until `excelUrl` is not `null`. `indexationSearchEngines` uses IDs from the supported search engines list referenced at the beginning of this documentation. #### Validation notes + If analyses contains `url`, at least one of `indexationSearchEngines` or `gsc=true` must be provided. + If `gsc=true`, field `gscProject` is required. + If analyses contains `page_analyser` and neither `indexationSearchEngines` nor `gsc=true` is provided, field `pageAnalysisSetup` is required. + If `pageAnalysisSetup` contains `keywordGetter`, result limits depend on the number of analysed URLs. ### Start URL Analysis [POST] + Attributes + urls (array[string], required) - List of absolute URLs to analyse. You can also send this field as a newline-separated string. + analyses (array[string], required) - List of analyses to run. + Members + url + page_analyser + label: My URL Analysis (string, optional) - Custom analysis label. + projectId: 123 (number, optional) - Target project ID. + countryCode: `CZ` (string, optional) - Country code used to resolve valid suggesters and keyword tools. If omitted, backend falls back to user default OTA country or client country. + gsc: true (boolean, optional) - Enables Google Search Console analysis for url analysis. + gscProject: 123 (number, optional) - Project ID used for GSC analysis. Required when gsc=true. + pageAnalysisSetup (array[string], optional) - Page analyser setup. Required when using page_analyser unless indexation/GSC setup is sufficient. + maxKeywords: 50 (number, optional) - Maximum number of keywords returned by keyword getter. + maxPhrases: 50 (number, optional) - Maximum number of phrases returned by keyword getter. + maxSpaces: 5 (number, optional) - Maximum number of spaces for keyword getter. + indexationSearchEngines (array[number], optional) - Search engine IDs used for indexation analysis. + Request + Headers Accept: application/collabim+json Content-Type: application/json Authorization: + Body { "urls": [ "https://www.example.com/", "https://www.example.com/category/" ], "analyses": [ "url", "page_analyser" ], "label": "Example URL analysis", "projectId": 123, "countryCode": "CZ", "indexationSearchEngines": [66], "gsc": true, "gscProject": 123, "pageAnalysisSetup": ["keywordGetter"], "maxKeywords": 50, "maxPhrases": 50, "maxSpaces": 5 } + Response 200 (application/json) + Body { "otaId": 12345 } + Response 400 (application/json) + Body { "errors": [ "Missing \"urls\"" ] } + Response 402 (application/json) + Body { "errors": [ "Payment required / setup failed" ] } ## URL Analysis Status [/url-analysis/status{?otaId}] Use this endpoint to check whether the URL Analysis export is ready. If the analysis is not finished yet `excelUrl` and `exportedAt` are null. ### Get URL Analysis status [GET] + Parameters + otaId: 12345 (number, required) - One-time analysis ID returned by the start endpoint. + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "excelUrl": null, "exportedAt": null } + Response 400 (application/json) + Body { "errors": [ "Missing otaId" ] } + Response 404 (application/json) + Body { "errors": [ "OTA not found" ] } + Response 403 (application/json) + Body { "errors": [ "Forbidden" ] } ## Website system [/website-system] You can detect what website system specific URL uses. This endpoint is pooling based! If you desire to use this endpoint, please contact us. **List of possible systems returned by endpoint:** wordpress, shoptet, eshop-rychle, byznys-web, upgates, fast-centrik, oxy-shop, webovy-servis, webnode, woocommerce, jzshop, shopion, webczech, wexbo, shoptec, open-servis, presta-shop, mio-web, magento, shop5, bizbox, ebrana, webmium, animato, 4shop, solidpixels, simplia, rocketoo, shopsys, simple-shop, fapi, smart-emailing, clipsan, web-eshop, binargon, clickeshop, shop_sun, webareal ### Website System Detection [GET] + Attributes + url: `https://example-eshop.com` (string, required) - URL for which you want to detect website system. + Request + Headers Accept: application/collabim+json Authorization: + Response 200 (application/json) + Body { "status": "success", "domain": "www.bezvapotisk.cz", "lastMeasured": "2021-04-19 16:35:13", "systems": [ "shoptet", "There can be many systems from list above." ] } + Response 200 (application/json) + Body { "status": "processing", "message": "We are currently detecting website system for requested domain. Please make this request later again." } + Response 200 (application/json) + Body { "status": "error", "message": "Detection failed, try again after 30 minutes, reason: Particular reason." } + Response 200 (application/json) + Body { "status": "error", "message": "Detection failed, try again after 30 minutes, reason: Unexpected failure, does this domain exist?" } + Response 400 (application/json) + Body { "status": "error", "message": "Parameter `url` is required." } + Response 401 (application/json) + Body { "message": "Unathorized access, please contact our support." }