Skip to main content
API docs by Redocly

CitizenLab OpenAPI Specification (2)

Download OpenAPI specification:Download

API Support: support@citizenlab.co URL: http://www.open-api.io/support License: Apache 2.0 Terms of Service

CitizenLab's public REST API is available for customers that want to programatically access data of the platform. This can be used to integrate the data in other tools, or to display CitizenLab content on another website..

Authentication

Contact support@citizenlab.co to get hold of your client_id and client_secret. Authenticate with your client_id and client_secret to retrieve a JWT token. You need to send the JWT token you got back along with every request to the API, as part of the Authorization header. The JWT token expires after 24h, so make sure to re-authenticate.

Retrieve a JWT token for authentication.

Endpoint to authenticate using client_id and client_secret to retrieve a JWT token.

Request Body schema: application/json
object
client_id
required
string

The client ID you obtained to access this API

client_secret
string

The client secret you obtained to access this API

Responses

Request samples

Content type
application/json
{
  • "auth": {
    }
}

Response samples

Content type
application/json
{
  • "jwt": "eyJhbGciOiJSUzI1NiJ9.eyJleHAiOjE2OTUzODY3MDIsInN1YiI6IjU0MjZkNTI5LTMyZDItNGFlYS1iMmIwLTgzNThlNmJiODMxNSJ9.APB9YBZQNEEUYPU0GxiHijs8JktGckFcwkShVZbdKP01WAMY-P97DGR50OvDdOS890QjLoLIF-N79LEJHOl5CWTTQmOqMecC1C6bcJFaWr2tJKwEqSUF_GcCObE1vUXdxMCgFKJQK8ULR4D0IstUVus_6S0JoXWrjof84woQSwpsXfpsTouwDsnp37Sh_UFbH9FUWH_Mo5mgtCsBqT8MaM0Mrjo1XAgS7zxCHRzV77opMWZZThHN1exan33CdlK3j_p0PaImdRPLo3p_AZGsW63ELjqrQeRsAZ-RgsU-_b-Ub6LJm8UtwJTr1UG9wLIgq8Cjo9ql2qEd-iaXbU6YAg"
}

Comments

All comments created on the platform

List all comments

Retrieve a paginated list of all the comments in the platform. You can filter the comments in different ways. For example, you can filter by "post type", or by date range.

Authorizations:
Authorization
query Parameters
locale
string

Which locale to return text for any multi-locale fields. For example: "en" or "fr-BE". If not provided, it will be set to the default language of the platform.

page_size
integer

The number of items that should be returned in one response. Defaults to 12, max 24

page_number
integer

The page to return. Defaults to page 1

created_at
string

Date the item was created - in format "YYYY-DD-MM" - to filter between two dates separate with comma

updated_at
string

Date item was last updated - in format "YYYY-DD-MM" - to filter between two dates separate with comma

post_type
string
Enum: "idea" "initiative"

List only the comments that were posted on a specific type of resource.

Responses

Response samples

Content type
application/json
{
  • "comments": [
    ],
  • "meta": {
    }
}

Get comment

Retrieve a single comment by its ID.

Authorizations:
Authorization
path Parameters
id
required
integer

Unique uuid for the item

id
required
string
query Parameters
locale
string

Which locale to return text for any multi-locale fields. For example: "en" or "fr-BE". If not provided, it will be set to the default language of the platform.

Responses

Response samples

Content type
application/json
{
  • "comment": {
    }
}

/api/v2/comments/deleted

Authorizations:
Authorization
query Parameters
deleted_at
string

Date item was deleted - in format "YYYY-DD-MM" - to filter between two dates separate with comma

Responses

Response samples

Content type
application/json
{
  • "deleted_items": [
    ],
  • "meta": {
    }
}

Idea topics

Idea topics represent associations between ideas and topics. This is a many-to-many relationship: Ideas can have multiple topics, and topics can be associated with multiple ideas.

/api/v2/idea_topics

Authorizations:
Authorization
query Parameters
idea_id
string

Filter by idea ID

topic_id
string

Filter by topic ID

Responses

Response samples

Content type
application/json
{
  • "idea_topics": [
    ],
  • "meta": {
    }
}

Posts

Posts are written inputs created by citizens. These can be ideas, initiatives (proposals), or survey responses.

List ideas

Retrieve a paginated list of all the ideas in the platform, with the most recent ones appearing first.

Authorizations:
Authorization
query Parameters
locale
string

Which locale to return text for any multi-locale fields. For example: "en" or "fr-BE". If not provided, it will be set to the default language of the platform.

page_size
integer

The number of items that should be returned in one response. Defaults to 12, max 24

page_number
integer

The page to return. Defaults to page 1

created_at
string

Date the item was created - in format "YYYY-DD-MM" - to filter between two dates separate with comma

updated_at
string

Date item was last updated - in format "YYYY-DD-MM" - to filter between two dates separate with comma

author_id
string

Filter by author ID

project_id
string

Filter by project ID

topic_ids
Array of strings

List only the ideas that have all of the specified topics

Responses

Response samples

Content type
application/json
{
  • "ideas": [
    ],
  • "meta": {
    }
}

Get idea

Retrieve a single idea by its ID.

Authorizations:
Authorization
path Parameters
id
required
integer

Unique uuid for the item

id
required
string
query Parameters
locale
string

Which locale to return text for any multi-locale fields. For example: "en" or "fr-BE". If not provided, it will be set to the default language of the platform.

Responses

Response samples

Content type
application/json
{
  • "idea": {
    }
}

/api/v2/ideas/deleted

Authorizations:
Authorization
query Parameters
deleted_at
string

Date item was deleted - in format "YYYY-DD-MM" - to filter between two dates separate with comma

Responses

Response samples

Content type
application/json
{
  • "deleted_items": [
    ],
  • "meta": {
    }
}

List initiatives

Retrieve a paginated list of all the initiatives in the platform, with the most recent ones appearing first.

Authorizations:
Authorization
query Parameters
locale
string

Which locale to return text for any multi-locale fields. For example: "en" or "fr-BE". If not provided, it will be set to the default language of the platform.

page_size
integer

The number of items that should be returned in one response. Defaults to 12, max 24

page_number
integer

The page to return. Defaults to page 1

created_at
string

Date the item was created - in format "YYYY-DD-MM" - to filter between two dates separate with comma

updated_at
string

Date item was last updated - in format "YYYY-DD-MM" - to filter between two dates separate with comma

Responses

Response samples

Content type
application/json
{
  • "initiatives": [
    ],
  • "meta": {
    }
}

Get initiative (proposal)

Retrieve a single initiative (proposal) by its ID.

Authorizations:
Authorization
path Parameters
id
required
integer

Unique uuid for the item

id
required
string
query Parameters
locale
string

Which locale to return text for any multi-locale fields. For example: "en" or "fr-BE". If not provided, it will be set to the default language of the platform.

Responses

Response samples

Content type
application/json
{
  • "initiative": {
    }
}

/api/v2/initiatives/deleted

Authorizations:
Authorization
query Parameters
deleted_at
string

Date item was deleted - in format "YYYY-DD-MM" - to filter between two dates separate with comma

Responses

Response samples

Content type
application/json
{
  • "deleted_items": [
    ],
  • "meta": {
    }
}

Phases

Phases represent the steps in a timeline project. Only timeline projects have phases, continuous projects do not.

List phases

Retrieve a paginated list of all the phases in the platform, with the most recently created ones first.

Authorizations:
Authorization
query Parameters
locale
string

Which locale to return text for any multi-locale fields. For example: "en" or "fr-BE". If not provided, it will be set to the default language of the platform.

page_size
integer

The number of items that should be returned in one response. Defaults to 12, max 24

page_number
integer

The page to return. Defaults to page 1

created_at
string

Date the item was created - in format "YYYY-DD-MM" - to filter between two dates separate with comma

updated_at
string

Date item was last updated - in format "YYYY-DD-MM" - to filter between two dates separate with comma

start_at
string

List only phases whose start date lies in the specified range. The range is specified as two dates separated by a comma: YYYY-MM-DD,YYYY-MM-DD. Open-ended ranges are also supported: YYYY-MM-DD, or ,YYYY-MM-DD.

end_at
string

List only phases whose end date lies in the specified range. The range is specified as two dates separated by a comma: YYYY-MM-DD,YYYY-MM-DD. Open-ended ranges are also supported: YYYY-MM-DD, or ,YYYY-MM-DD.

Responses

Response samples

Content type
application/json
{
  • "phases": [
    ],
  • "meta": {
    }
}

List all the phases of a project

Endpoint to retrieve phases of a single project. The phases are returned in reverse order of date created. The endpoint supports pagination.

Authorizations:
Authorization
path Parameters
project_id
required
string
query Parameters
locale
string

Which locale to return text for any multi-locale fields. For example: "en" or "fr-BE". If not provided, it will be set to the default language of the platform.

page_size
integer

The number of items that should be returned in one response. Defaults to 12, max 24

page_number
integer

The page to return. Defaults to page 1

created_at
string

Date the item was created - in format "YYYY-DD-MM" - to filter between two dates separate with comma

updated_at
string

Date item was last updated - in format "YYYY-DD-MM" - to filter between two dates separate with comma

Responses

Response samples

Content type
application/json
{
  • "phases": [
    ],
  • "meta": {
    }
}

Get phase

Retrieve a single phase by its ID.

Authorizations:
Authorization
path Parameters
id
required
integer

Unique uuid for the item

id
required
string
query Parameters
locale
string

Which locale to return text for any multi-locale fields. For example: "en" or "fr-BE". If not provided, it will be set to the default language of the platform.

Responses

Response samples

Content type
application/json
{
  • "phase": {
    }
}

/api/v2/phases/deleted

Authorizations:
Authorization
query Parameters
deleted_at
string

Date item was deleted - in format "YYYY-DD-MM" - to filter between two dates separate with comma

Responses

Response samples

Content type
application/json
{
  • "deleted_items": [
    ],
  • "meta": {
    }
}

Project Folders

Projects folders are used to group projects together.

List project folders

Retrieve a paginated list of all the project folders in the platform.

Authorizations:
Authorization
query Parameters
locale
string

Which locale to return text for any multi-locale fields. For example: "en" or "fr-BE". If not provided, it will be set to the default language of the platform.

page_size
integer

The number of items that should be returned in one response. Defaults to 12, max 24

page_number
integer

The page to return. Defaults to page 1

created_at
string

Date the item was created - in format "YYYY-DD-MM" - to filter between two dates separate with comma

updated_at
string

Date item was last updated - in format "YYYY-DD-MM" - to filter between two dates separate with comma

publication_status
string
Enum: "draft" "published" "archived"

List only project folders with the given publication status

Responses

Response samples

Content type
application/json
{
  • "project_folders/folders": [
    ],
  • "meta": {
    }
}

Get project folder

Retrieve a single project folder by its ID.

Authorizations:
Authorization
path Parameters
id
required
integer

Unique uuid for the item

id
required
string
query Parameters
locale
string

Which locale to return text for any multi-locale fields. For example: "en" or "fr-BE". If not provided, it will be set to the default language of the platform.

Responses

Response samples

Content type
application/json
{
  • "project_folders/folder": {
    }
}

/api/v2/project_folders/deleted

Authorizations:
Authorization
query Parameters
deleted_at
string

Date item was deleted - in format "YYYY-DD-MM" - to filter between two dates separate with comma

Responses

Response samples

Content type
application/json
{
  • "deleted_items": [
    ],
  • "meta": {
    }
}

Project topics

Project topics represent associations between projects and topics. This is a many-to-many relationship: Projects can have multiple topics, and topics can be associated with multiple projects.

/api/v2/project_topics

Authorizations:
Authorization
query Parameters
project_id
string

Filter by project ID

topic_id
string

Filter by topic ID

Responses

Response samples

Content type
application/json
{
  • "project_topics": [
    ],
  • "meta": {
    }
}

Projects

Projects are participation scopes. They establish a framework, including the context, duration, and expected input, to encourage citizens to actively engage in focused discussions. Within these projects, citizens can contribute and post their ideas.

List projects

Retrieve a paginated list of all the projects in the platform, with the newest projects appearing first.

Authorizations:
Authorization
query Parameters
locale
string

Which locale to return text for any multi-locale fields. For example: "en" or "fr-BE". If not provided, it will be set to the default language of the platform.

page_size
integer

The number of items that should be returned in one response. Defaults to 12, max 24

page_number
integer

The page to return. Defaults to page 1

created_at
string

Date the item was created - in format "YYYY-DD-MM" - to filter between two dates separate with comma

updated_at
string

Date item was last updated - in format "YYYY-DD-MM" - to filter between two dates separate with comma

folder_id
string

List only the projects that are in the specified folder.

publication_status
string
Enum: "draft" "published" "archived"

List only the projects that have the specified publication status.

topic_ids
Array of any

List only the projects that have all the specified topics.

Responses

Response samples

Content type
application/json
{
  • "projects": [
    ],
  • "meta": {
    }
}

Get project

Retrieve a single project by ID.

Authorizations:
Authorization
path Parameters
id
required
integer

Unique uuid for the item

id
required
string
query Parameters
locale
string

Which locale to return text for any multi-locale fields. For example: "en" or "fr-BE". If not provided, it will be set to the default language of the platform.

Responses

Response samples

Content type
application/json
{
  • "project": {
    }
}

/api/v2/projects/deleted

Authorizations:
Authorization
query Parameters
deleted_at
string

Date item was deleted - in format "YYYY-DD-MM" - to filter between two dates separate with comma

Responses

Response samples

Content type
application/json
{
  • "deleted_items": [
    ],
  • "meta": {
    }
}

Reactions

All reactions created in the platform

List all reactions

Retrieve a paginated list of all the reactions in the platform. You can filter the reactions in different ways. For example, you can filter by "reactable type" (the type of resource that was reacted to), by user identifier, or by date range.

Authorizations:
Authorization
query Parameters
locale
string

Which locale to return text for any multi-locale fields. For example: "en" or "fr-BE". If not provided, it will be set to the default language of the platform.

page_size
integer

The number of items that should be returned in one response. Defaults to 12, max 24

page_number
integer

The page to return. Defaults to page 1

created_at
string

Date the item was created - in format "YYYY-DD-MM" - to filter between two dates separate with comma

updated_at
string

Date item was last updated - in format "YYYY-DD-MM" - to filter between two dates separate with comma

reactable_type
string
Enum: "idea" "initiative" "comment" "idea-comment" "initiative-comment"

List only the reactions that were cast on a specific type of resource. 'initiative' corresponds to proposals on the platform. 'idea-comment' and 'initiative-comment' filter reactions on comments on ideas and comments on proposals, respectively.

user_id
string

List only the reactions that were cast by a specific user.

Responses

Response samples

Content type
application/json
{
  • "reactions": [
    ],
  • "meta": {
    }
}

Topics

Topics, referred to as tags within the platform, are utilized to label the content on the platform, including project, contributions, and pages.

List topics

Retrieve a paginated list of all the topics in the platform, with the most recently created ones first.

Authorizations:
Authorization
query Parameters
locale
string

Which locale to return text for any multi-locale fields. For example: "en" or "fr-BE". If not provided, it will be set to the default language of the platform.

page_size
integer

The number of items that should be returned in one response. Defaults to 12, max 24

page_number
integer

The page to return. Defaults to page 1

created_at
string

Date the item was created - in format "YYYY-DD-MM" - to filter between two dates separate with comma

updated_at
string

Date item was last updated - in format "YYYY-DD-MM" - to filter between two dates separate with comma

Responses

Response samples

Content type
application/json
{
  • "topics": [
    ],
  • "meta": {
    }
}

Get topic

Retrieve a single topic by its ID.

Authorizations:
Authorization
path Parameters
id
required
integer

Unique uuid for the item

id
required
string
query Parameters
locale
string

Which locale to return text for any multi-locale fields. For example: "en" or "fr-BE". If not provided, it will be set to the default language of the platform.

Responses

Response samples

Content type
application/json
{
  • "topic": {
    }
}

/api/v2/topics/deleted

Authorizations:
Authorization
query Parameters
deleted_at
string

Date item was deleted - in format "YYYY-DD-MM" - to filter between two dates separate with comma

Responses

Response samples

Content type
application/json
{
  • "deleted_items": [
    ],
  • "meta": {
    }
}

Users

All user registrations on the platform.

List users

Retrieve a paginated list of all the users in the platform, with the most recently created ones first.

Authorizations:
Authorization
query Parameters
locale
string

Which locale to return text for any multi-locale fields. For example: "en" or "fr-BE". If not provided, it will be set to the default language of the platform.

page_size
integer

The number of items that should be returned in one response. Defaults to 12, max 24

page_number
integer

The page to return. Defaults to page 1

created_at
string

Date the item was created - in format "YYYY-DD-MM" - to filter between two dates separate with comma

updated_at
string

Date item was last updated - in format "YYYY-DD-MM" - to filter between two dates separate with comma

Responses

Response samples

Content type
application/json
{
  • "users": [
    ],
  • "meta": {
    }
}

Get user

Retrieve a single user by its ID.

Authorizations:
Authorization
path Parameters
id
required
integer

Unique uuid for the item

id
required
string
query Parameters
locale
string

Which locale to return text for any multi-locale fields. For example: "en" or "fr-BE". If not provided, it will be set to the default language of the platform.

Responses

Response samples

Content type
application/json
{
  • "user": {
    }
}

/api/v2/users/deleted

Authorizations:
Authorization
query Parameters
deleted_at
string

Date item was deleted - in format "YYYY-DD-MM" - to filter between two dates separate with comma

Responses

Response samples

Content type
application/json
{
  • "deleted_items": [
    ],
  • "meta": {
    }
}