Skip to main content
API docs by Redocly

API V1 (v0.0)

Download OpenAPI specification:Download

A RestFull API for Decidim, to be able to CRUD resources from Decidim.

Authentication

Get a token from our /oauth/token routes, following OAuth specs on Credential Flows or Resource Owner Password Credentials Flow.

Permissions

A permission system is attached to the created OAuth application, that is designed in two levels:

  • scope: a broad permission to access a collection of endpoints
  • abilities: a fine grained permission system that allow actions.

The scopes and abilities are manageable in your System Admin Panel.

Multi-tenant

Decidim is multi-tenant, and this API supports it.

  • The system scope endpoints are available in any tenant
  • The tenant host attribute will be used to guess which tenant you are requesting. For example, given a tenant example.org and foobar.org, the endpoint
    • example.org/oauth/token will ask a token for the example.org organization
    • foobar.org/oauth/token for foobar.org.

OAuth

Use OAuth to get tokens and interact with the API. You can use machine-to-machine tokens, or user token directly with the API.

  • Machine-to-machine: Client Credential Flow
  • User: Resource Owner Password Credential Flow, with impersonation or login
How to authenticate

Introspect a OAuth token

Get given oauth token details

Authorizations:
credentialFlowBearerresourceOwnerFlowBearer
Request Body schema: application/json
required
token
string
required
any

Responses

Request samples

Content type
application/json
{
  • "token": "string",
  • "required": null
}

Response samples

Content type
application/json
Example
{
  • "active": true,
  • "scope": "public",
  • "client_id": "2XQRsRr7nFlmoYtR33CDM-pdcBAgui39smMnsu585DI",
  • "token_type": "Bearer",
  • "exp": 3470895558,
  • "iat": 1734108579,
  • "sub": 7631,
  • "aud": "https://1.lvh.me"
}

Request a OAuth token throught ROPC

Create a oauth token for the given scopes

Request Body schema: application/json
required
One of
grant_type
required
string
Value: "client_credentials"

Client Credential Flow, for machine-to-machine

client_id
required
string

OAuth application Client Id

client_secret
required
string

OAuth application Client Secret

scope
required
string
Enum: "public" "spaces" "system" "proposals" "meetings" "debates" "pages"

Requested scopes

Responses

Request samples

Content type
application/json
Example
{
  • "grant_type": "client_credentials",
  • "client_id": "string",
  • "client_secret": "string",
  • "scope": "public"
}

Response samples

Content type
application/json
Example
{
  • "access_token": "Rw3sotCldDNorsPg5whc2NOO2oK3JAuyMkhnvOmkbnI",
  • "token_type": "Bearer",
  • "expires_in": 7200,
  • "scope": "public",
  • "created_at": 1734108586
}

Public

List Components

List or search components of the organization

Authorizations:
credentialFlowBearerresourceOwnerFlowBearer
query Parameters
locales[]
Array of strings
Items Enum: "en" "bg" "ar" "ca" "cs" "da" "de" "el" "eo" "es" "es-MX" "es-PY" "et" "eu" "fa" "fi-pl" "fi" "fr" "fr-CA" "ga" "gl" "hr" "hu" "id" "is" "it" "ja" "ko" "lb" "lt" "lv" "mt" "nl" "no" "pl" "pt" "pt-BR" "ro" "ru" "sk" "sl" "sr" "sv" "tr" "uk" "vi" "zh-CN" "zh-TW"

accepted locales in response

filter[manifest_name_not_in][]
Array of strings
Items Enum: "pages" "proposals" "meetings" "budgets" "surveys" "accountability" "debates" "sortitions" "blogs"

match none of manifest_name's values in array

filter[manifest_name_in][]
Array of strings
Items Enum: "pages" "proposals" "meetings" "budgets" "surveys" "accountability" "debates" "sortitions" "blogs"

match one of manifest_name's values in array

filter[manifest_name_eq]
string

manifest_name is equal to

filter[manifest_name_not_eq]
string

manifest_name is NOT equal to

filter[participatory_space_id_in][]
Array of strings

match one of participatory_space_id's values in array

filter[participatory_space_id_eq]
string

participatory_space_id is equal to

filter[participatory_space_type_in][]
Array of strings
Example: filter[participatory_space_type_in][]=Decidim::Assembly

match one of participatory_space_type's values in array

filter[participatory_space_type_eq]
string

participatory_space_type is equal to

filter[name_start]
string
Example: filter[name_start]=some_string

name starts with

filter[name_eq]
string

name is equal to

filter[name_not_eq]
string

name is NOT equal to

filter[name_matches]
string
Example: filter[name_matches]=%some_string

matches name with LIKE

page
integer

Page number for pagination

per_page
integer

Number of items per page

Responses

Response samples

Content type
application/json
Example
{
  • "data": [
    ]
}

Show a Component

Get details of a component

Authorizations:
credentialFlowBearerresourceOwnerFlowBearer
path Parameters
id
required
integer
query Parameters
locales[]
Array of strings
Items Enum: "en" "bg" "ar" "ca" "cs" "da" "de" "el" "eo" "es" "es-MX" "es-PY" "et" "eu" "fa" "fi-pl" "fi" "fr" "fr-CA" "ga" "gl" "hr" "hu" "id" "is" "it" "ja" "ko" "lb" "lt" "lv" "mt" "nl" "no" "pl" "pt" "pt-BR" "ro" "ru" "sk" "sl" "sr" "sv" "tr" "uk" "vi" "zh-CN" "zh-TW"

accepted locales in response

Responses

Response samples

Content type
application/json
Example
{
  • "data": {
    }
}

List Participatory Spaces

List or search spaces of the organization. Can be processes, assemblies, or any other registred participatory space.

Authorizations:
credentialFlowBearerresourceOwnerFlowBearer
query Parameters
locales[]
Array of strings
Items Enum: "en" "bg" "ar" "ca" "cs" "da" "de" "el" "eo" "es" "es-MX" "es-PY" "et" "eu" "fa" "fi-pl" "fi" "fr" "fr-CA" "ga" "gl" "hr" "hu" "id" "is" "it" "ja" "ko" "lb" "lt" "lv" "mt" "nl" "no" "pl" "pt" "pt-BR" "ro" "ru" "sk" "sl" "sr" "sv" "tr" "uk" "vi" "zh-CN" "zh-TW"

accepted locales in response

filter[manifest_name_not_in][]
Array of strings
Items Enum: "participatory_processes" "assemblies"

match none of manifest_name's values in array

filter[manifest_name_in][]
Array of strings
Items Enum: "participatory_processes" "assemblies"

match one of manifest_name's values in array

filter[manifest_name_eq]
string

manifest_name is equal to

filter[manifest_name_not_eq]
string

manifest_name is NOT equal to

filter[title_not_in][]
Array of strings

match none of title's values in array

filter[title_in][]
Array of strings

match one of title's values in array

filter[title_start]
string
Example: filter[title_start]=some_string

title starts with

filter[title_not_start]
string
Example: filter[title_not_start]=some_string

title does not starts with

filter[title_eq]
string

title is equal to

filter[title_not_eq]
string

title is NOT equal to

filter[title_matches]
string
Example: filter[title_matches]=%some_string

matches title with LIKE

filter[title_does_not_match]
string

Does not matches title with LIKE

filter[title_present]
string
Enum: "1" "0"
Example: filter[title_present]=1

title is not null and not empty

filter[title_blank]
string
Enum: "1" "0"
Example: filter[title_blank]=1

title is null or empty

page
integer

Page number for pagination

per_page
integer

Number of items per page

Responses

Response samples

Content type
application/json
Example
{
  • "data": [
    ]
}

Show Participatory Space

Get detail of a space given its manifest and id

Authorizations:
credentialFlowBearerresourceOwnerFlowBearer
path Parameters
id
required
integer

Id of the space

manifest_name
required
string
Enum: "participatory_processes" "assemblies"

Type of space

query Parameters
locales[]
Array of strings
Items Enum: "en" "bg" "ar" "ca" "cs" "da" "de" "el" "eo" "es" "es-MX" "es-PY" "et" "eu" "fa" "fi-pl" "fi" "fr" "fr-CA" "ga" "gl" "hr" "hu" "id" "is" "it" "ja" "ko" "lb" "lt" "lv" "mt" "nl" "no" "pl" "pt" "pt-BR" "ro" "ru" "sk" "sl" "sr" "sv" "tr" "uk" "vi" "zh-CN" "zh-TW"

accepted locales in response

Responses

Response samples

Content type
application/json
Example
{
  • "data": {
    }
}

System

List available organizations

List available organizations

Authorizations:
credentialFlowBearer
query Parameters
locales[]
Array of strings
Items Enum: "en" "bg" "ar" "ca" "cs" "da" "de" "el" "eo" "es" "es-MX" "es-PY" "et" "eu" "fa" "fi-pl" "fi" "fr" "fr-CA" "ga" "gl" "hr" "hu" "id" "is" "it" "ja" "ko" "lb" "lt" "lv" "mt" "nl" "no" "pl" "pt" "pt-BR" "ro" "ru" "sk" "sl" "sr" "sv" "tr" "uk" "vi" "zh-CN" "zh-TW"

accepted locales in response

page
integer

Page number for pagination

per_page
integer

Number of items per page

Responses

Response samples

Content type
application/json
Example
{
  • "data": [
    ]
}

List available Users

List or search users of the organization

Authorizations:
credentialFlowBearer
query Parameters
page
integer

Page number for pagination

per_page
integer

Number of items per page

filter[nickname_not_in][]
Array of strings

match none of nickname's values in array

filter[nickname_in][]
Array of strings

match one of nickname's values in array

filter[nickname_start]
string
Example: filter[nickname_start]=some_string

nickname starts with

filter[nickname_not_start]
string
Example: filter[nickname_not_start]=some_string

nickname does not starts with

filter[nickname_eq]
string

nickname is equal to

filter[nickname_not_eq]
string

nickname is NOT equal to

filter[nickname_matches]
string
Example: filter[nickname_matches]=%some_string

matches nickname with LIKE

filter[nickname_does_not_match]
string

Does not matches nickname with LIKE

filter[nickname_present]
string
Enum: "1" "0"
Example: filter[nickname_present]=1

nickname is not null and not empty

filter[nickname_blank]
string
Enum: "1" "0"
Example: filter[nickname_blank]=1

nickname is null or empty

filter[extra_cont]
string
Example: filter[extra_cont]="foo": "bar"

Search on user extended_data. use the format: "<key>":<space>"<value>"

Responses

Response samples

Content type
application/json
Example
{
  • "data": [
    ]
}