Cikisi API Documentation
Cikisi 3.0 WEB API
Welcome to Cikisi 3.0 API.
Quick reference
These parameters are always necessary, not only when signing in.
Header Optional
access-token false token-type false expiry false uid false customer false
Questions/Comments
If you have any questions or comments, please let us know at:getoar.gashi@cikisi.com
DISCLAIMER
{{variables}} are just there to pinpoint that you have to use your own values or values that we agreed upon such as {{API-url}} and {{VERSION}}.
{{API-url}} – https://app.cikisi.com/api{{version}} – v2
THIS IS BY NO MEANS AN ENVIRONMENT.
Authentication Process
In the response headers (if authentication was successful) these five parameters can be found:
– access-token
– token-type
– expiry
– uid
– client
These five parameters are REQUIRED to make further requests to our API. These should be sent in the request headers.
These parameters should be included (in the headers) in every request made to our API.
Please check the image below.
General Parameters
All parameters below are OPTIONAL
– per_page
The per_page parameter allows you to configure the maximum amount of hits to be returned
– page
The page parameter defines the Items that are published after that date.
– date_from
Date from defines Items that are published after that date. (When publication date is not available in the orignal page, or not well identified by Cikisi, then the publication date is linked to the creation date)
– date_to
Date to defines Items that are published until that date. (When publication date is not available in the orignal page, or not well identified by Cikisi, then the publication date is linked to the creation date)
– sort_by
Sort by defines in which way you want to sort fetched Items: [publication_date, created_at, relevance, engagements, views]
– sort_direction
Sort direction defines in what order to view the items: [ASC, DESC]
– metadata
The value by default (metadata=0) allows you to receive the items with their basic metadata: [ id, title, description, content, publication_date, created_at, source information ] Metadata=1 allows you to receive the items with all the metadata including [ Name Entities and keywords, collections, tags, geolocations ]
Auth
User Authorization
POST
/auth/sign_in
{{CIKISI_URL}}/api/auth/sign_in
Params
Email
Body {Formdata}
Field Value
Email {{Email}}Password {{Password}}
curl --location -g '{{CIKISI_URL}}/api/auth/sign_in' \
--form 'email="{{Email}}"' \
--form 'password="{{Password}}"'
Collection Items
GET /v2/collections/:id/items
{{CIKISI_URL}}/api/v2/collections/:id/items?per_page={{10}}&page={{0}}&date_from={{Date}}&date_to={{Date}}&sort_by={{Sort}}&sort_direction={{Sort Direction}}
Headers
Header Value
access-token {{access-token}}token-type {{token-type}}customer {{Client}}expiry {{expiry}}uid {{uid}}
Params
Name Value
per_page {{10}}page {{0}}date_form {{date}}date_to {{date}}sort_by {{sort}}sort_direction {{Sort Direction}}
PATH VARIABLES
Name Value id {{collection_id}}
curl --location -g '{{CIKISI_URL}}/api/v2/collections/{{collection_id}}/items?per_page={{10}}&page={{0}}&date_from={{Date}}&date_to={{Date}}&sort_by={{Sort}}&sort_direction={{Sort%20Direction}}' \
--header 'access-token: {{Access-Token}}' \
--header 'token-type: {{Token-Type}}' \
--header 'client: {{Client}}' \
--header 'expiry: {{Expiry}}' \
--header 'uid: {{Uid}}'
Topic Items
GET /v2/topics/:id/items
{{CIKISI_URL}}/api/v2/topics/:id/items?per_page={{10}}&page={{0}}&date_from={{Date}}&date_to={{Date}}&sort_by={{Sort}}&sort_direction={{Sort Direction}}
Headers
Header Value
access-token {{access-token}}token-type {{token-type}}customer {{Client}}expiry {{expiry}}uid {{uid}}
Params
Name Value
per_page {{10}}page {{0}}date_form {{date}}date_to {{date}}sort_by {{sort}}sort_direction {{Sort}}{{Sort Direction}}
PATH VARIABLES
Theme Items
GET /v2/themes/:id/items
{{CIKISI_URL}}/api/v2/themes/:id/items?per_page={{10}}&page={{0}}&date_from={{Date}}&date_to={{Date}}&sort_by={{Sort}}&sort_direction={{Sort Direction}}
Headers
Header Value
access-token {{access-token}}token-type {{token-type}}customer {{Client}}expiry {{expiry}}uid {{uid}}
Params
Name Value
per_page {{10}}page {{0}}date_form {{date}}date_to {{date}}sort_by {{sort}}sort_direction {{Sort Direction}}
PATH VARIABLES
curl --location -g '{{CIKISI_URL}}/api/v2/themes/{{theme_id}}/items?per_page={{10}}&page={{0}}&date_from={{Date}}&date_to={{Date}}&sort_by={{Sort}}&sort_direction={{Sort%20Direction}}' \
--header 'access-token: {{Access-Token}}' \
--header 'token-type: {{Token-Type}}' \
--header 'client: {{Client}}' \
--header 'expiry: {{Expiry}}' \
--header 'uid: {{Uid}}'
Source Items
GET /v2/sources/:id/items
{{CIKISI_URL}}/api/v2/sources/:id/items?per_page={{10}}&page={{0}}&date_from={{Date}}&date_to={{Date}}&sort_by={{Sort}}&sort_direction={{Sort Direction}}
Headers
Header Value
access-token {{access-token}}token-type {{token-type}}customer {{Client}}expiry {{expiry}}uid {{uid}}
Params
Name Value
per_page {{10}}page {{0}}date_form {{date}}date_to {{date}}sort_by {{sort}}sort_direction {{Sort Direction}}
PATH VARIABLES
curl --location -g '{{CIKISI_URL}}/api/v2/sources/{{source_id}}/items?per_page={{10}}&page={{0}}&date_from={{Date}}&date_to={{Date}}&sort_by={{Sort}}&sort_direction={{Sort%20Direction}}' \
--header 'access-token: {{Access-Token}}' \
--header 'token-type: {{Token-Type}}' \
--header 'client: {{Client}}' \
--header 'expiry: {{Expiry}}' \
--header 'uid: {{Uid}}'
Tags Items
GET /v2/item_tags/items
{{CIKISI_URL}}/api/v2/item_tags/items? name[]={{Tag Names}}&per_page={{10}}&page={{0}}&date_from={{Date}}&date_to={{Date}}&sort_by={{Sort}}&sort_direction={{Sort Direction}}
Headers
Header Value
access-token {{access-token}}token-type {{token-type}}customer {{Client}}expiry {{expiry}}uid {{uid}}
PATH VARIABLES
Name Value
Name {{Tag Names}}per_page {{10}}page {{0}}date_form {{date}}date_to {{date}}sort_by {{sort}}sort_direction {{Sort Direction}}
curl --location -g '{{CIKISI_URL}}/api/v2/item_tags/items?name[]={{Tag%20Names}}&per_page={{10}}&page={{0}}&date_from={{Date}}&date_to={{Date}}&sort_by={{Sort}}&sort_direction={{Sort%20Direction}}' \
--header 'access-token: {{Access-Token}}' \
--header 'token-type: {{Token-Type}}' \
--header 'client: {{Client}}' \
--header 'expiry: {{Expiry}}' \
--header 'uid: {{Uid}}'
Source Categories Items
GET /v2/source_categories/items
https://www.wmt.cikisi.com/api
Headers
Header Value
access-token {{access-token}}token-type {{token-type}}customer {{Client}}expiry {{expiry}}uid {{uid}}
PATH VARIABLES
Name Value
Name {{Categories Names}}per_page {{10}}page {{0}}date_form {{date}}date_to {{date}}sort_by {{sort}}sort_direction {{Sort Direction}}
Geolocated Items
GET /v2/geolocated/items
{{CIKISI_URL}}api/v2/geolocated/items?radius={{Radius}}&lat={{Latitude}}&lon={{Longitude}}&keywords={{Keywords}}&per_page={{10}}&page={{0}}&date_from={{Date}}&date_to={{Date}}&sort_by={{Sort}}&sort_direction={{Sort Direction}}
Headers
Header Value
access-token {{access-token}}token-type {{token-type}}customer {{Client}}expiry {{expiry}}uid {{uid}}
PATH VARIABLES
Name Value
radius {{Radius}}lat {{Latitude}}lon {{Longitude}}keywords {{Keywords}}per_page {{10}}page {{0}}date_form {{date}}date_to {{date}}sort_by {{sort}}sort_direction {{Sort Direction}}
curl --location -g '{{CIKISI_URL}}api/v2/geolocated/items?radius={{Radius}}&lat={{Latitude}}&lon={{Longitude}}&keywords={{Keywords}}&per_page={{10}}&page={{0}}&date_from={{Date}}&date_to={{Date}}&sort_by={{Sort}}&sort_direction={{Sort%20Direction}}' \
--header 'access-token: {{Access-Token}}' \
--header 'token-type: {{Token-Type}}' \
--header 'client: {{Client}}' \
--header 'expiry: {{Expiry}}' \
--header 'uid: {{Uid}}'
(Cikisi Saved) Searches Items
GET /v2/searches/:id/items
{{CIKISI_URL}}/api/v2/searches/:id/items?per_page={{10}}&page={{0}}&date_from={{Date}}&date_to={{Date}}&sort_by={{Sort}}&sort_direction={{Sort Direction}}
Headers
Header Value
access-token {{access-token}}token-type {{token-type}}customer {{Client}}expiry {{expiry}}uid {{uid}}
PATH VARIABLES
Name Value
per_page {{10}}page {{0}}date_from {{Date}}date_to {{Date}}sort_by {{Sort}}sort_direction {{Sort Direction}}
PATH VARIABLES
Name Value id {{collection_id}}
Similar Items
GET /v2/similar/items
{{CIKISI_URL}}/api/v2/similar/items?title={{title}}&content={{content}}&per_page={{10}}&page={{0}}&date_from={{Date}}&date_to={{Date}}&sort_by={{Sort}}&sort_direction={{Sort Direction}}
Headers
Header Value
access-token {{access-token}}token-type {{token-type}}customer {{Client}}expiry {{expiry}}uid {{uid}}
PATH VARIABLES
Name Value
title {{Categories Names}}content {{Categories Names}}per_page {{10}}page {{0}}date_form {{date}}date_to {{date}}sort_by {{sort}}sort_direction {{Sort Direction}}
Search Items
GET /v2/search
{{CIKISI_URL}}/api/v2/search?keywords={{keywords}}
Write your query using keywords AND/OR/NOT/*/ operators, in capital letters. You can also use brackets for grouping.
Eg.: ( football OR soccer ) AND ( “world cup” OR olymp* ) NOT (Brazil OR USA)
Headers
Header Value
access-token {{access-token}}token-type {{token-type}}customer {{Client}}expiry {{expiry}}uid {{uid}}
PARAMS
Name Value
title {{Categories Names}}content {{Categories Names}}per_page {{10}}page {{0}}date_form {{date}}date_to {{date}}sort_by {{sort}}sort_direction {{Sort Direction}}
Create Items
GET /v2/create_article
{{CIKISI_URL}}/api/v2/create_article
Headers
Header Value
access-token {{access-token}}token-type {{token-type}}customer {{Client}}expiry {{expiry}}uid {{uid}}
PARAMS
Name Value
title - String {{title}}description - String {{description}}content - String CONTENToriginal_url - String {{URL}}image_url - String {{image_url}}image - String {{ }}collections - Array [ID(Integer)],author - String {{author}}language - String, eg: "en" for English {{en}}publication_date - DateTime, eg: "2025-10-22T07:49:00.000Z" {{pub date}}
Update Items
GET /v2/update_article/:id
{{CIKISI_URL}}/api/v2/update_article/:id
Headers
Header Value
access-token {{access-token}}token-type {{token-type}}customer {{Client}}expiry {{expiry}}uid {{uid}}
PARAMS
Name Value
title - String {{title}}description - String {{description}}content - String CONTENToriginal_url - String {{URL}}image_url - String {{image_url}}image - String {{ }}collections - Array [ID(Integer)],author - String {{author}}language - String, eg: "en" for English {{en}}publication_date - DateTime, eg: "2025-10-22T07:49:00.000Z" {{pub date}}
Book a demo 
