Cikisi API Documentation

Cikisi 3.0 WEB API

Cikisi logo in blue.

Welcome to Cikisi 3.0 API.
Here you can find all available requests to our API.

Quick reference

These parameters are always necessary, not only when signing in.

HeaderOptional
access-tokenfalse
token-typefalse
expiryfalse
uidfalse
clientfalse

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.
These parameters are always necessary, not only when signing in.

Please check the image below.

Headers example placeholder

General Parameters

All parameters below are OPTIONAL

Some parameters must be used in combination:

  • date_from and date_to: Iso 8601 date format is accepted, in short or long format (ex : 2026-06-19, 2026-06-17T14:03:39, 2026-06-17T14:03:39.000Z)
  • sort_by and sort_direction
  • per_page and page.
If you use them individually, they will be ignored.

– 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}

FieldValue
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}}

By default, the date_from and date_to parameters are applied to the publication date. If you want to filter articles by date added to the collection you can use the parameter : get_by=created_at_col. This parameter is only necessary in that case ; if it is missing the publication date is applied by default.

Headers

HeaderValue
access-token{{access-token}}
token-type{{token-type}}
client{{Client}}
expiry{{expiry}}
uid{{uid}}

Params

NameValue
per_page{{10}}
page{{0}}
date_form{{date}}
date_to{{date}}
sort_by{{sort}}
sort_direction{{Sort Direction}}
get_by{{created_at_col}}

PATH VARIABLES

NameValue
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

HeaderValue
access-token{{access-token}}
token-type{{token-type}}
client{{Client}}
expiry{{expiry}}
uid{{uid}}

Params

NameValue
per_page{{10}}
page{{0}}
date_form{{date}}
date_to{{date}}
sort_by{{sort}}
sort_direction{{Sort}}{{Sort Direction}}

PATH VARIABLES

NameValue
id{{topic_id}}

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

HeaderValue
access-token{{access-token}}
token-type{{token-type}}
client{{Client}}
expiry{{expiry}}
uid{{uid}}

Params

NameValue
per_page{{10}}
page{{0}}
date_form{{date}}
date_to{{date}}
sort_by{{sort}}
sort_direction{{Sort Direction}}

PATH VARIABLES

NameValue
id{{Theme_Id}}
 
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

HeaderValue
access-token{{access-token}}
token-type{{token-type}}
client{{Client}}
expiry{{expiry}}
uid{{uid}}

Params

NameValue
per_page{{10}}
page{{0}}
date_form{{date}}
date_to{{date}}
sort_by{{sort}}
sort_direction{{Sort Direction}}

PATH VARIABLES

NameValue
id{{Theme_Id}}
 
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

HeaderValue
access-token{{access-token}}
token-type{{token-type}}
client{{Client}}
expiry{{expiry}}
uid{{uid}}

PATH VARIABLES

NameValue
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
/v2/source_categories/items?name[]={{Categories Names}}&per_page={{10}}&page={{0}}&date_from={{Date}}&date_to={{Date}}&sort_by={{Sort}}&sort_direction={{Sort Direction}}

Headers

HeaderValue
access-token{{access-token}}
token-type{{token-type}}
client{{Client}}
expiry{{expiry}}
uid{{uid}}

PATH VARIABLES

NameValue
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

HeaderValue
access-token{{access-token}}
token-type{{token-type}}
client{{Client}}
expiry{{expiry}}
uid{{uid}}

PATH VARIABLES

NameValue
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

HeaderValue
access-token{{access-token}}
token-type{{token-type}}
client{{Client}}
expiry{{expiry}}
uid{{uid}}

PATH VARIABLES

NameValue
per_page{{10}}
page{{0}}
date_from{{Date}}
date_to{{Date}}
sort_by{{Sort}}
sort_direction{{Sort Direction}}

PATH VARIABLES

NameValue
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

HeaderValue
access-token{{access-token}}
token-type{{token-type}}
client{{Client}}
expiry{{expiry}}
uid{{uid}}

PATH VARIABLES

NameValue
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

HeaderValue
access-token{{access-token}}
token-type{{token-type}}
client{{Client}}
expiry{{expiry}}
uid{{uid}}

PARAMS

NameValue
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

POST/v2/create_article

{{CIKISI_URL}}/api/v2/create_article

Headers

HeaderValue
access-token{{access-token}}
token-type{{token-type}}
client{{Client}}
expiry{{expiry}}
uid{{uid}}

PARAMS

NameValue
title - String{{title}}
description - String{{description}}
content - StringCONTENT
original_url - String{{URL}}
image_url - String{{image_url}}
image - String{{ }}
collections - Array[ID(Integer)],
tags - 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}}
files - Arraymultipart/form-data

Update Items

GET/v2/update_article/:id

{{CIKISI_URL}}/api/v2/update_article/:id

Headers

HeaderValue
access-token{{access-token}}
token-type{{token-type}}
client{{Client}}
expiry{{expiry}}
uid{{uid}}

PARAMS

NameValue
title - String{{title}}
description - String{{description}}
content - StringCONTENT
original_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}}

Knowledge topics

GET/v2/collections

{{CIKISI_URL}}/api/v2/collections/

List tags

GET/v2/tags

{{CIKISI_URL}}/api/v2/tags/

Unlock the Power
of Strategic Insights

Camera Icon Book a demo