Concrete CMS REST API - Endpoints

Edit

Improvements?

Let us know by posting here.

  Note: This updated API functionality is available in Concrete version 9.2+

Below are the available endpoints and some example code for accessing them via the API.

Sections:

Account Endpoint

GET /ccm/api/1.0/account

Description: Returns information about the currently logged in user.

Parameters: No Parameters

Responses:

200:

{
  "id": "string",
  "username": "string",
  "email": "string",
  "date_added": "2023-02-23",
  "date_password_last_changed": "2023-02-23",
  "date_last_updated": "2023-02-23",
  "status": "string",
  "total_logins": "string",
  "has_avatar": "string",
  "avatar": "string",
  "last_login": 0,
  "previous_login": 0,
  "timezone": "string",
  "language": "string",
  "custom_attributes": [
    {
      "id": 0,
      "type": "string",
      "key": "string",
      "value": {}
    }
  ]
}

Area Endpoints

POST /ccm/api/1.0/pages/{pageID}/{areaHandle}

Description: Add a block to a page area.

Parameters:

  • pageID - Required - integer($int64) - ID of the page

  • areaHandle - Required - string - Area name

Request Body - Required - string - Block object that needs to be added to the CMS

NewBlock Model

{
    type:   string (Block Type Handle)
    value:  Block value {
        (Key/Value object that maps to the request array that powers the block editing interface.)
    }

}

Responses:

200:

{
  "id": 0,
  "type": "string",
  "value": {}
}

PUT /ccm/api/1.0/pages/{pageID}/{areaHandle}/{blockID}

Description: Update a block within a page area.

Parameters:

  • pageID - Required - integer($int64) - ID of the page

  • areaHandle - Required - string - Area name

  • blockID - Required - integer($int64) - ID of block

Request Body - Required - Block object updated through the CMS

UpdatedBlock Model

{
    value:  Block value {
        (Key/Value object that maps to the request array that powers the block editing interface.)
    }
}

Responses:

200:

{
  "id": "string",
  "object": "string",
  "deleted": true,
  "version": {
    "id": 0,
    "is_approved": "string",
    "date_created": "2023-02-24",
    "date_approved": "2023-02-24",
    "publish_end_date": "2023-02-24"
  }
}

DELETE /ccm/api/1.0/pages/{pageID}/{areaHandle}/{blockID}

Description: Deletes a block from a page area.

Parameters:

  • pageID - Required - integer($int64) - ID of the page

  • areaHandle - Required - string - Area name

  • blockID - Required - integer($int64) - ID of block

Responses:

{
  "id": "string",
  "object": "string",
  "deleted": true,
  "version": {
    "id": 0,
    "is_approved": "string",
    "date_created": "2023-02-24",
    "date_approved": "2023-02-24",
    "publish_end_date": "2023-02-24"
  }
}

Block Endpoints

GET /ccm/api/1.0/blocks/{blockID}

Description: Returns information about the currently logged in user.

Parameters: * blockID - Required - integer($int64) - ID of block to return * includes - Optional - array[string] - Available values: pages

Responses:

{
  "id": 0,
  "type": "string",
  "value": {}
}

DELETE /ccm/api/1.0/blocks/{blockID}

Description: Delete a block by its ID.

Parameters:

  • blockID - Required - integer($int64) - ID of block

Responses:

200:

{
  "id": "string",
  "object": "string",
  "deleted": true
}

401:

You do not have the proper permissions to delete this resource.

404:

Block not found

File Endpoints

GET /ccm/api/1.0/files/{fileID}

Description: Find a file by its ID

Parameters: * fileID - Required - integer($int64) - ID of file to return * includes - Optional - array[string] - Available values : custom_attributes

Responses:

200:

{
  "id": "string",
  "uuid": "string",
  "url": "string",
  "tracked_url": "string",
  "file_type": "string",
  "extension": "string",
  "title": "string",
  "description": "string",
  "tags": "string",
  "date_added": "2023-02-24",
  "size": {},
  "custom_attributes": [
    {
      "id": 0,
      "type": "string",
      "key": "string",
      "value": {}
    }
  ]
}

401:

You do not have the proper permissions to access this resource.

404: File not found

PUT /ccm/api/1.0/files/{fileID}

Description: Update a file by its ID.

Parameters:

  • fileID - ID of file to update

Request Body - Required - File object updated through the CMS

UpdatedFile Model

{
  "title": "string",
  "description": "string",
  "tags": "string",
  "attributes": {
    "width": "string",
    "height": "string",
    "duration": "string"
  }
}

Responses:

200:

{
  "id": "string",
  "uuid": "string",
  "url": "string",
  "tracked_url": "string",
  "file_type": "string",
  "extension": "string",
  "title": "string",
  "description": "string",
  "tags": "string",
  "date_added": "2023-02-24",
  "size": {},
  "custom_attributes": [
    {
      "id": 0,
      "type": "string",
      "key": "string",
      "value": {}
    }
  ]
}

401: You do not have the proper permissions to update this resource.

404: File not found

DELETE /ccm/api/1.0/files/{fileID}

Description: Delete a file by its ID.

Parameters:

  • fileID - Required - integer($int64) - ID of file to delete

Responses:

200:

{
  "id": "string",
  "object": "string",
  "deleted": true
}

401:

You do not have the proper permissions to delete this resource.

404:

File not found

GET /ccm/api/1.0/files

Description: Returns a list of file objects, sorted by last updated descending. The most recent file objects appear first.

Parameters:

  • limit - Optional - integer($int64) - The number of objects to return. Must be 100 or less. Defaults to 10.

  • after - Optional - integer($int64) -
    The ID of the current object to start at.

  • includes - Optional - array[string] - Available values: custom_attributes

Responses:

200:

[
  {
    "id": "string",
    "uuid": "string",
    "url": "string",
    "tracked_url": "string",
    "file_type": "string",
    "extension": "string",
    "title": "string",
    "description": "string",
    "tags": "string",
    "date_added": "2023-02-24",
    "size": {},
    "custom_attributes": [
      {
        "id": 0,
        "type": "string",
        "key": "string",
        "value": {}
      }
    ]
  }
]

POST /ccm/api/1.0/files

Description: Adding a file to the CMS.

Parameters:

No Parameters.

Request Body - Required - multipart/form-data - Adding a file to the CMS

folder: integer

file: string($binary)

Responses:

200:

{
  "id": "string",
  "uuid": "string",
  "url": "string",
  "tracked_url": "string",
  "file_type": "string",
  "extension": "string",
  "title": "string",
  "description": "string",
  "tags": "string",
  "date_added": "2023-02-24",
  "size": {},
  "custom_attributes": [
    {
      "id": 0,
      "type": "string",
      "key": "string",
      "value": {}
    }
  ]
}

POST /ccm/api/1.0/files/{fileID}/move

Description: Move a file to a new location.

Parameters:

  • fileID - Required - integer - ID of file to update

Request Body - Required - multipart/form-data - Adding a file to the CMS

folder: integer

Responses:

200:

{
  "id": "string",
  "uuid": "string",
  "url": "string",
  "tracked_url": "string",
  "file_type": "string",
  "extension": "string",
  "title": "string",
  "description": "string",
  "tags": "string",
  "date_added": "2023-02-24",
  "size": {},
  "custom_attributes": [
    {
      "id": 0,
      "type": "string",
      "key": "string",
      "value": {}
    }
  ]
}

401:

You do not have the proper permissions to update this resource.

404:

File not found

Groups Endpoints

GET /ccm/api/1.0/groups/{groupID}

Description: Find a user group by its ID.

Parameters:

  • groupID - Required - integer($int64) - ID of group.

Responses:

200:

{
  "name": "string",
  "id": 0
}

401:

You do not have the proper permissions to access this resource.

404:

Group not found

GET /ccm/api/1.0/groups

Description: Returns a list of Group objects, sorted by ID ascending.

Parameters:

  • limit - Optional - integer($int64) - The number of objects to return. Must be 100 or less. Defaults to 10.
  • after - Optional - integer($int64) - The ID of the current object to start after.

Responses

200:

[
  {
    "name": "string",
    "id": 0
  }
]

POST /ccm/api/1.0/groups

Description: Adds a Group object.

Parameters:

No Parameters.

Request Body - Required - application/json - Group object that needs to be added to the CMS.

{
  "name": "string"
}

Responses:

200:

{
  "name": "string"
}

Pages Endpoints

GET /ccm/api/1.0/pages/{pageID}

Description: Find a page by its ID

Parameters:

  • pageID - Required - integer($int64) - ID of Page to return.

  • includes - array[string] - Available values : custom_attributes, areas, files, content, areas.content

  • version - string - Return the active version (default) or the most recent version - Available values : active, recent

Responses:

200:

{
  "id": 0,
  "path": "string",
  "name": "string",
  "type": "string",
  "template": "string",
  "date_added": "2024-08-29",
  "date_last_updated": "2024-08-29",
  "locale": "2024-08-29",
  "external_link_url": "string",
  "description": "string",
  "custom_attributes": [
    {
      "id": 0,
      "type": "string",
      "key": "string",
      "value": "string"
    }
  ],
  "areas": [
    {
      "name": "string",
      "blocks": [
        {
          "id": 0,
          "type": "string",
          "value": {}
        }
      ],
      "content": {
        "content": "string",
        "raw": "string"
      }
    }
  ],
  "files": [
    {
      "id": "string",
      "uuid": "string",
      "url": "string",
      "tracked_url": "string",
      "file_type": "string",
      "extension": "string",
      "title": "string",
      "description": "string",
      "tags": "string",
      "date_added": "2024-08-29",
      "size": {},
      "folder": 0,
      "custom_attributes": [
        {
          "id": 0,
          "type": "string",
          "key": "string",
          "value": "string"
        }
      ]
    }
  ],
  "content": {
    "content": "string",
    "raw": "string"
  },
  "version": {
    "id": 0,
    "is_approved": "string",
    "date_created": "2024-08-29",
    "date_approved": "2024-08-29",
    "publish_end_date": "2024-08-29"
  }
}

PUT /ccm/api/1.0/sites/

Description: Update a page by its ID.

Parameters:

  • pageID - Required - integer($int64) - ID of Page to return.

Request Body - Required - multipart/form-data - Page object updated through the CMS.

UpdatedPage model

{
    name: string
    description: string
    type: string
    template: string
    attributes: {
        meta_title: string
        meta_description:   string
        meta_keywords:  string
        exclude_nav:    boolean
        exclude_page_list:  boolean
        header_extra_content:   string
        tags:   integer
        is_featured:    boolean
        exclude_search_index:   boolean
        exclude_sitemapxml: boolean
        exclude_subpages_from_nav:  boolean
        thumbnail:  number
    }
}

Responses:

200:

{
  "id": 0,
  "path": "string",
  "name": "string",
  "type": "string",
  "template": "string",
  "date_added": "2024-08-29",
  "date_last_updated": "2024-08-29",
  "locale": "2024-08-29",
  "external_link_url": "string",
  "description": "string",
  "custom_attributes": [
    {
      "id": 0,
      "type": "string",
      "key": "string",
      "value": "string"
    }
  ],
  "areas": [
    {
      "name": "string",
      "blocks": [
        {
          "id": 0,
          "type": "string",
          "value": {}
        }
      ],
      "content": {
        "content": "string",
        "raw": "string"
      }
    }
  ],
  "files": [
    {
      "id": "string",
      "uuid": "string",
      "url": "string",
      "tracked_url": "string",
      "file_type": "string",
      "extension": "string",
      "title": "string",
      "description": "string",
      "tags": "string",
      "date_added": "2024-08-29",
      "size": {},
      "folder": 0,
      "custom_attributes": [
        {
          "id": 0,
          "type": "string",
          "key": "string",
          "value": "string"
        }
      ]
    }
  ],
  "content": {
    "content": "string",
    "raw": "string"
  },
  "version": {
    "id": 0,
    "is_approved": "string",
    "date_created": "2024-08-29",
    "date_approved": "2024-08-29",
    "publish_end_date": "2024-08-29"
  }
}

DELETE /ccm/api/1.0/pages/{pageID}

Description: Delete a page by its ID.

Parameters:

  • pageID - Required - integer($int64) - ID of Page to return.

Responses:

200: Successful operation

{
  "id": "string",
  "object": "string",
  "deleted": true
}

Sites Endpoints

GET /ccm/api/1.0/sites/{siteID}

Description: Find a site by its ID.

Parameters:

Site ID - Required - integer($int64) - ID of Site to return.

Responses:

200:

{
  "id": 0,
  "handle": "string",
  "name": "string",
  "home_page_id": 0,
  "default_locale": "string",
  "locales": [
    {
      "id": 0,
      "country": "string",
      "language": "string",
      "home_page_id": 0
    }
  ]
}

GET /ccm/api/1.0/sites/default

Description: Retrieve the default site for your Concrete installation

Parameters:

  • includes - Optional - array[string] - Available values: locales, custom_attributes

Responses:

200:

{
  "id": 0,
  "handle": "string",
  "name": "string",
  "home_page_id": 0,
  "default_locale": "string",
  "locales": [
    {
      "id": 0,
      "country": "string",
      "language": "string",
      "home_page_id": 0
    }
  ]
}

System Endpoints

GET /ccm/api/1.0/system/info

Description: Retrieve System Info about your site.

Parameters:

None

Responses:

200:

The info object in JSON format

Users Endpoints

GET /ccm/api/1.0/users/{userID}

Description: Find a user by its ID

Parameters:

  • includes - Optional - array[string] - Available values: groups, custom_attributes

Responses:

200:

{
  "id": "string",
  "username": "string",
  "email": "string",
  "date_added": "2023-03-30",
  "date_password_last_changed": "2023-03-30",
  "date_last_updated": "2023-03-30",
  "status": "string",
  "total_logins": "string",
  "has_avatar": "string",
  "avatar": "string",
  "last_login": 0,
  "previous_login": 0,
  "timezone": "string",
  "language": "string",
  "custom_attributes": [
    {
      "id": 0,
      "type": "string",
      "key": "string",
      "value": "string"
    }
  ]
}

PUT /ccm/api/1.0/users/{userID}

Description: Update a user by its ID

Parameters:

  • userID - required - integer($int64) - ID of user to update

Request Body

{
  "username": "string",
  "email": "string",
  "language": "string",
  "attributes": {
    "profile_private_messages_enabled": true,
    "profile_private_messages_notification_enabled": true,
    "account_profile_links": [
      {
        "service": "string",
        "service_info": "string"
      }
    ]
  }
}

Responses:

200:

{
  "id": "string",
  "username": "string",
  "email": "string",
  "date_added": "2023-03-30",
  "date_password_last_changed": "2023-03-30",
  "date_last_updated": "2023-03-30",
  "status": "string",
  "total_logins": "string",
  "has_avatar": "string",
  "avatar": "string",
  "last_login": 0,
  "previous_login": 0,
  "timezone": "string",
  "language": "string",
  "custom_attributes": [
    {
      "id": 0,
      "type": "string",
      "key": "string",
      "value": "string"
    }
  ]
}

401:

You do not have the proper permissions to update this resource.

404:

User not found

DELETE /ccm/api/1.0/users/{userID}

Description: Delete a user by its ID

Parameters:

  • userID - required - integer($int64) - ID of user to delete

Responses:

200:

{
  "id": "string",
  "object": "string",
  "deleted": true
}

401:

You do not have the proper permissions to update this resource.

404:

User not found

GET /ccm/api/1.0/users

Description: Returns a list of user objects, sorted by date added descending. The most recent user objects appear first.

Parameters:

  • limit - optional - integer($int64) - The number of objects to return. Must be 100 or less. Defaults to 10.
  • after - optional - integer($int64) - The ID of the current object to start at.
  • includes - optional - array[string] - Available values: custom_attributes, groups

Responses:

200:

[
  {
    "id": "string",
    "username": "string",
    "email": "string",
    "date_added": "2023-03-30",
    "date_password_last_changed": "2023-03-30",
    "date_last_updated": "2023-03-30",
    "status": "string",
    "total_logins": "string",
    "has_avatar": "string",
    "avatar": "string",
    "last_login": 0,
    "previous_login": 0,
    "timezone": "string",
    "language": "string",
    "custom_attributes": [
      {
        "id": 0,
        "type": "string",
        "key": "string",
        "value": "string"
      }
    ]
  }
]

POST /ccm/api/1.0/users}

Description: Adds a user object.

Parameters:

None

Request Body

{
  "username": "string",
  "email": "string",
  "password": "string",
  "language": "string"
}

Responses:

200:

{
  "id": "string",
  "username": "string",
  "email": "string",
  "date_added": "2023-03-30",
  "date_password_last_changed": "2023-03-30",
  "date_last_updated": "2023-03-30",
  "status": "string",
  "total_logins": "string",
  "has_avatar": "string",
  "avatar": "string",
  "last_login": 0,
  "previous_login": 0,
  "timezone": "string",
  "language": "string",
  "custom_attributes": [
    {
      "id": 0,
      "type": "string",
      "key": "string",
      "value": "string"
    }
  ]
}

POST /ccm/api/1.0/users/{userID}/change_password

Description: Change a user's password.

Parameters:

userID - Required - integer($int64) - ID of user to update

Request Body

password (string)

Responses:

200:

{
  "id": "string",
  "username": "string",
  "email": "string",
  "date_added": "2023-03-30",
  "date_password_last_changed": "2023-03-30",
  "date_last_updated": "2023-03-30",
  "status": "string",
  "total_logins": "string",
  "has_avatar": "string",
  "avatar": "string",
  "last_login": 0,
  "previous_login": 0,
  "timezone": "string",
  "language": "string",
  "custom_attributes": [
    {
      "id": 0,
      "type": "string",
      "key": "string",
      "value": "string"
    }
  ]
}

401:

You do not have the proper permissions to update this resource.

404:

User not found

Page Versions Endpoint

GET /ccm/api/1.0/page_versions/{pageID}/{versionID}

Description: Find a page version by its ID and the ID of its page.

Parameters:

  • pageID - Required - integer($int64) - ID of page
  • versionID - Required - integer($int64) - ID of page version

Responses:

200:

{
  "id": 0,
  "is_approved": "string",
  "date_created": "2023-03-30",
  "date_approved": "2023-03-30",
  "publish_end_date": "2023-03-30"
}

401:

You do not have the proper permissions to update this resource.

404:

Page version not found

PUT /ccm/api/1.0/page_versions/{pageID}/{versionID}

Description: Update a page version

Parameters:

  • pageID - required - integer($int64) - ID of page to update
  • versionID - required - integer($int64) - ID of user to update

Request Body

{
  "is_approved": true,
  "publish_end_date": "2023-03-30"
}

Responses:

200:

{
  "id": 0,
  "is_approved": "string",
  "date_created": "2023-03-30",
  "date_approved": "2023-03-30",
  "publish_end_date": "2023-03-30"
}

401:

You do not have the proper permissions to update this resource.

404:

Version not found

DELETE /ccm/api/1.0/page_versions/{pageID}/{versionID}

Description: Delete a page version.

Parameters:

  • pageID - required - integer($int64) - ID of page
  • versionID - required - integer($int64) - ID of page version

Responses:

200:

{
  "id": "string",
  "object": "string",
  "deleted": true
}

401:

You do not have the proper permissions to update this resource.

404:

Page Version not found

GET /ccm/api/1.0/page_versions/{pageID}

Description: Returns a list of page version objects for a given page ID, sorted by date created descending.

Parameters:

  • pageID - Required - integer($int64) - ID of page
  • limit - Optional - integer($int64) - The number of objects to return. Must be 100 or less. Defaults to 10.
  • resultsPage - Optional - integer($int64) - The page of results to retrieve. Default is 1.

Responses:

200:

[
  {
    "id": 0,
    "is_approved": "string",
    "date_created": "2023-03-30",
    "date_approved": "2023-03-30",
    "publish_end_date": "2023-03-30"
  }
]