Back to top

Movable Type Data API v3

The Movable Type Data API is a REST interface to the Movable Type Content Management System. The Data API is available for Movable Type Pro and Movable Type Advanced / Enterprise, Version 6.0 and higher.

Movable Type Data API v3 was released in Movable Type 6.0

Movable Type > 開発者向け ドキュメント > Movable Type Data API ドキュメント

Common API

Common API

Version

Get server API version
GET/version

Retrieves Data API version of the server.

This endpoint is available in Movable Type 6.2.4 or later.

This endpoint does not need /v3 or something API endpoint version identifier.
You can call like: https://host/path/your-mt-data-api.cgi/version

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/version
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "endpointVersion": "v3",
  "apiVersion": "3.01"
}

Authentication

Authentication

User authentication by username and password
POST/authentication

Create a new session and access token. This is like sign-in.

Example URI

POST http://your-host/path-to-mt/mt-data-api.cgi/v3/authentication
Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Body
username={Your Sign-in Name}&password={Your Web Service Password}&clientId={Your Client ID}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "accessToken": "EowKdyeBcEUNbiFEXlp0bdQz5RJgdkJYLbBDRJ4m",
  "sessionId": "8VtaTLTLp8V9OR5Dz40hO7by8wf0wbCsCkBue0Xv",
  "expiresIn": 3600,
  "remember": false
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "code": 401,
    "message": "Invalid login"
  }
}

Invalidate current session
DELETE/authentication

Invalidate current session. This is like sign-out. All access tokens related to that session will invalidated too.

This method accepts DELETE or POST with __method=DELETE.

Example URI

DELETE http://your-host/path-to-mt/mt-data-api.cgi/v3/authentication
Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
X-MT-Authorization: MTAuth sessionId={session_id}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": "success"
}

User authentication via sing-in Screen
GET/authorization?{redirectUrl,clientId}

When this endpoint called from application, user will move to sign-in screen of Movable Type.
And then user will move to new location that specified in the redirectUrl parameter when user has been authenticated.

If your application is running on web browser, you should use this endpoint instead of /authenticatoin.

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/authorization?redirectUrl&clientId
URI Parameters
HideShow
redirectUrl
string (required) 

Specify the redirect location where the user moves after sign in.

clientId
string (required) 

The client identifier.

Response  200
HideShow
Headers
Content-Type: text/html

Token

Create a new access token
POST/token

Create a new access token that related to current session.

Example URI

POST http://your-host/path-to-mt/mt-data-api.cgi/v3/token
Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
X-MT-Authorization: MTAuth sessionId={SessionId}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
      "accessToken" : "EowKdyeBcEUNbiFEXlp0bdQz5RJgdkJYLbBDRJ4m",
      "expiresIn" : 3600,
    }
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "code": 401,
    "message": "Unauthorized"
  }
}

Invalidate current access token. This is not sign-out.
DELETE/token

Invalidate current access token. This is not sign-out. If the browser has active session ID, new access token can be obtained easily.

This method accepts DELETE and POST with __method=DELETE.

Example URI

DELETE http://your-host/path-to-mt/mt-data-api.cgi/v3/token
Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
X-MT-Authorization: MTAuth accessToken={AccessToken}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": "success"
}

Assets

This is the Assets resource.

  • Model (application/json)
Property Name Type Data Type Database Column Private Read Only Description Version
blog object - The blog of this asset. v2
blog.id value number mt_asset.asset_blog_id Y The ID of the blog that contains this asset. v2
class value string mt_asset.asset_class Y The type of this asset. This value is similar to ‘type’ attribute but this value is never localized. v2
createdBy Object - Y The user who created this asset. v2
createdBy.id value number mt_asset.asset_created_by Y Y The ID of user who created asset. v2
createdBy.displayName value string Y The display name of user who created asset. v2
createdBy.userpicUrl value string Y The URL of creating user’s userpic. The userpic will be made by UserpicThumbnailSize and UserpicAllowRect settings. If user does not set own userpic, empty string will be returned. v2
createdDate value iso 8601 datetime mt_asset.asset_created_on Y The created time for this asset. v2
customFields ARRAY - The list of customfields data for this asset. v2
customFields.basename value string mt_field.field_basename The basename of this customfield. v2
customFields.value value string The value of this customfield. v2
description value string mt_asset_asset_description The description of this asset. v1
fileExt value string mt_asset.asset_file_ext Y The file extension of this asset. Returns the file extension without the leading period. v2
filename value string mt_asset.asset_filename Y The filename of this asset that includes file extension. v1
id value number mt_asset.asset_id Y The ID of this asset. v1
label value string mt_asset.asset_label The label of this asset. v1
meta object - The meta information of this asset. v2
meta.fileSize value number Y The file size of this asset. If this asset is not file-based asset, will return null. v2
meta.height value number Y The height of this asset. If this asset has no height meta information, will return null. v2
meta.width value number Y The width of this asset. If this asset has no width meta information, will return null. v2
mimeType value string mt_asset.asset_mime_type Y The MIME Type of this asset. v1
modifiedBy Object - Y The user who last modified this asset. v2
modifiedBy.displayName value string Y The display name of user who last modified asset. v2
modifiedBy.id value number mt_asset.asset_modified_by Y Y The ID of user who last modified asset. v2
modifiedBy.userpicUrl value string Y The URL of last modified user’s userpic. The userpic will be made by UserpicThumbnailSize and UserpicAllowRect settings. If user does not set own userpic, empty string will be returned. v2
modifiedDate value iso 8601 datetime mt_asset.asset_modified_on Y The last modified time for this asset. v2
parent object - The parent asset of this asset. If this asset is not a child of any assets, will return null. v2
parent.id value number asset_parent Y The ID of parent asset. v2
tags ARRAY string A list of tags associated with this asset. v1
type value string mt_asset.asset_class Y The type of this asset. The value returned will be localized value with DefaultLanguage. v2
updatable value boolean Y
true
The user who accessed can update this asset.
false
The user who accessed cannot update this asset.
 v2
url value string mt_asset.asset_url Y The permalink URL of this asset. v1

{ “createdBy” : { “id” : 1 “userpicUrl” : “/mt-static/support/assets_c/userpics/userpic-1-100x100.png”, “displayName” : “Yuji Takayama” }, “updatable” : false, “meta” : { “width” : “800”, “fileSize” : 194272, “height” : “600” }, “url” : "http://example.com/images/1ab89ee2.jpg", “id” : “5”, “modifiedDate” : “2014-11-05T12:59:36+09:00”, “modifiedBy” : { “id” : 1 “userpicUrl” : “/mt-static/support/assets_c/userpics/userpic-1-100x100.png”, “displayName” : “Yuji Takayama” }, “parent” : null, “blog” : { “id” : “22” }, “description” : “Cat photo”, “tags” : [ “black”, “cat”, “white” ], “filename” : “1ab89ee2.jpg”, “type” : “Images”, “mimeType” : “image/jpeg”, “label” : “Cat One”, “createdDate” : “2014-11-05T12:58:52+09:00”, “class” : “image”, “customFields” : [], “fileExtension” : “jpg” },

Upload

Upload a single file.
POST/assets/upload{?overwrite_once}

Upload a single file.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to upload file.
404 Not Found Site not found.
409 Conflict Uploaded file already exists.
413 Request Entity Too Large Upload file size is larger than CGIMaxUpload.

Permissions

  • upload

Request Body Parameters

Name Type Required Default Description
site_id number Yes The site ID.
path string Yes The upload destination. You can specify the path to be under the site path.
file file Yes Actual file data
autoRenameIfExists boolean false If this value is true and a file with the same filename exists, the uploaded file is automatically renamed to a random generated name.
normalizeOrientation boolean true If this value is true and the uploaded file has orientation information in Exif data, this file’s orientation is automatically normalized.

Example URI

POST http://your-host/path-to-mt/mt-data-api.cgi/v3/assets/upload?overwrite_once=
URI Parameters
HideShow
overwrite_once
number (optional) 

If specify “1”, the API always overwrites an existing file with the uploaded file. This parameter is available in Movable Type 6.1.2

Request  multipart/form-data
HideShow
Body
site_id=1&path=/images&file={filedata}&autoRenameIfExists=true&normalizeOrientation=false
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": 1,
  "label": "The Bridge",
  "mimeType": "image/jpeg",
  "url": "http://example.com/images/the-bridge.jpg",
  "filename": "the-bridge",
  "description": "Taken from over the bridge.",
  "tags": [
    "boston",
    "bridge",
    "light"
  ],
  "blog": {
    "id": 1
  },
  "updatable": true,
  "modifiedBy": {
    "id": 1,
    "displayName": "Yuji Takayama",
    "userpicUrl": null
  },
  "modifiedDate": "2014-10-10T13:13:01+09:00",
  "createdBy": {
    "id": 1,
    "displayName": "Yuji Takayama",
    "userpicUrl": null
  },
  "cratedDate": "2014-10-10T13:13:01+09:00",
  "type": "Image",
  "class": "image",
  "fileExt": "jpg",
  "parent": {
    "id": null
  },
  "meta": {
    "height": 768,
    "width": 1024,
    "fileSize": 339773
  }
}

DEPRECATED - Upload a single file.
POST/sites/{site_id}/assets/upload

This endpoint is marked as deprecated in v2.0.

Upload single file to specific site.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to upload file.
404 Not Found Site not found.
409 Conflict Uploaded file already exists.
413 Request Entity Too Large Upload file size is larger than CGIMaxUpload.

Permissions

  • upload
Name Type Required Default Description
path string Yes The upload destination. You can specify the path to be under the site path. This parameter is required.
file file Yes Actual file data
autoRenameIfExists boolean false If this value is true and a file with the same filename exists, the uploaded file is automatically renamed to a random generated name.
normalizeOrientation boolean true If this value is true and the uploaded file has orientation information in Exif data, this file’s orientation is automatically normalized.

Example URI

POST http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/assets/upload
URI Parameters
HideShow
site_id
number (required) 

The site ID.

Request
HideShow
Headers
Content-Type: multipart/form-data
Body
path=/images&file={filedata}&autoRenameIfExists=true&normalizeOrientation=false
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": 1,
  "label": "The Bridge",
  "mimeType": "image/jpeg",
  "url": "http://example.com/images/the-bridge.jpg",
  "filename": "the-bridge",
  "description": "Taken from over the bridge.",
  "tags": [
    "boston",
    "bridge",
    "light"
  ],
  "blog": {
    "id": 1
  },
  "updatable": true,
  "modifiedBy": {
    "id": 1,
    "displayName": "Yuji Takayama",
    "userpicUrl": null
  },
  "modifiedDate": "2014-10-10T13:13:01+09:00",
  "createdBy": {
    "id": 1,
    "displayName": "Yuji Takayama",
    "userpicUrl": null
  },
  "cratedDate": "2014-10-10T13:13:01+09:00",
  "type": "Image",
  "class": "image",
  "fileExt": "jpg",
  "parent": {
    "id": null
  },
  "meta": {
    "height": 768,
    "width": 1024,
    "fileSize": 339773
  }
}

Assets

Retrieve a list of assets.
GET/sites/{site_id}/assets{?search,searchFields,limit,offset,class,sortBy,sortOrder,fields,relatedAssets,dateField,dateFrom,dateTo}

Retrieve list of assets in the specified site.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to retrieve the list of assets.
404 Not Found Site not found.

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/assets?search=&searchFields=&limit=&offset=&class=&sortBy=&sortOrder=&fields=&relatedAssets=&dateField=&dateFrom=&dateTo=
URI Parameters
HideShow
site_id
number (required) 

The site ID. If 0 specified, will retrieve system-level assets.

search
string (optional) 

Search query.

searchFields
string (optional) Default: label 

The comma separated list of field names to search.

limit
number (optional) Default: 10 

Maximum number of assets to retrieve.

offset
number (optional) Default: 0 

0-indexed offset.

class
string (optional) 

The target asset class to retrieve. Supported values are 'image’, 'audio’, 'video’, 'file’, and any values added by plugins. If you want to retrieve multiple classes, specify the values separated by commas.

sortBy
string (optional) Default: created_on 
file_name
Sort by the filename of each asset.
created_by
Sort by the ID of user who created each asset.
created_on
(default) Sort by the created time of each asset.
sortOrder
string (optional) Default: descend 
descend
(default) Return assets in descending order. For sorting by date, it means from newest to oldest.
ascend
Return assets in ascending order. For sorting by date, it means from oldest to newest.
fields
string (optional) 

The field list to retrieve as part of the Assets resource. The list of field names should be separated by commas. If this parameter is not specified, all fields will be returned.

relatedAssets
boolean (optional) 

If you want to retrieve related assets (e.g. thumbnail, popup html) that generated by original asset, you should specify this parameter as true.

dateField
string (optional) Default: created_on 

Specifies the field name to be used as a date field for filtering. (new in v3)

dateFrom
string (optional) 

The start date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

dateTo
string (optional) 

The end date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults" : 1,
  "items" : [
  {
    "id" : 1,
    "label" : "The Bridge",
    "mimeType" : "image/jpeg",
    "url" : "http://example.com/images/the-bridge.jpg",
    "filename" : "the-bridge",
    "description" : "Taken from over the bridge.",
    "tags" : [
      "boston",
      "bridge",
      "light"
    ],
    "blog" : {
      "id" : 1
    },
    "updatable" : true,
    "modifiedBy" : {
      "id" : 1,
      "displayName" : "Yuji Takayama",
      "userpicUrl" : null
    },
    "modifiedDate" : "2014-10-10T13:13:01+09:00",
    "createdBy" : {
      "id" : 1,
      "displayName" : "Yuji Takayama",
      "userpicUrl" : null
    },
    "cratedDate" : "2014-10-10T13:13:01+09:00",
    "type" : "Image",
    "class" : "image",
    "fileExt" : "jpg",
    "parent" : {
      "id" : null
    },
    "meta" : {
      "height" : 768,
      "width" : 1024,
      "fileSize" : 339773
    }
  ]
}

Retrieve a list of assets that related with entry
GET/sites/{site_id}/entries/{entry_id}/assets{?limit,offset,class,sortBy,sortOrder,fields,dateField,dateFrom,dateTo}

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to retrieve the list of assets.
404 Not Found Site or entry not found.

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/entries/entry_id/assets?limit=&offset=&class=&sortBy=&sortOrder=&fields=&dateField=&dateFrom=&dateTo=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

entry_id
number (required) 

The entry ID.

limit
number (optional) Default: 10 

Maximum number of assets to retrieve.

offset
number (optional) Default: 0 

0-indexed offset.

class
string (optional) 

The target asset class to retrieve. Supported values are image, audio, video, file and any values added by plugins. If you want to retrieve multiple classes, specify the values separated by commas.

sortBy
string (optional) Default: created_on 
file_name
Sort by the filename of each asset.
created_by
Sort by the ID of user who created each asset.
created_on
(default) Sort by the created time of each asset.
sortOrder
string (optional) Default: descend 
descend
(default) Return assets in descending order. For sorting by date, it means from newest to oldest.
ascend
Return assets in ascending order. For sorting by date, it means from oldest to newest.
fields
string (optional) 

The field list to retrieve as part of the Assets resource. The list of field names should be separated by commas. If this parameter is not specified, all fields will be returned.

dateField
string (optional) Default: created_on 

Specifies the field name to be used as a date field for filtering. (new in v3)

dateFrom
string (optional) 

The start date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

dateTo
string (optional) 

The end date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults" : 1,
  "items" : [
  {
    "id" : 1,
    "label" : "The Bridge",
    "mimeType" : "image/jpeg",
    "url" : "http://example.com/images/the-bridge.jpg",
    "filename" : "the-bridge",
    "description" : "Taken from over the bridge.",
    "tags" : [
      "boston",
      "bridge",
      "light"
    ],
    "blog" : {
      "id" : 1
    },
    "updatable" : true,
    "modifiedBy" : {
      "id" : 1,
      "displayName" : "Yuji Takayama",
      "userpicUrl" : null
    },
    "modifiedDate" : "2014-10-10T13:13:01+09:00",
    "createdBy" : {
      "id" : 1,
      "displayName" : "Yuji Takayama",
      "userpicUrl" : null
    },
    "cratedDate" : "2014-10-10T13:13:01+09:00",
    "type" : "Image",
    "class" : "image",
    "fileExt" : "jpg",
    "parent" : {
      "id" : null
    },
    "meta" : {
      "height" : 768,
      "width" : 1024,
      "fileSize" : 339773
    }
  ]
}

Retrieve a list of assets that related with page
GET/sites/{site_id}/pages/{page_id}/assets{?limit,offset,class,sortBy,sortOrder,fields,dateField,dateFrom,dateTo}

Retrieve assets that related with specified page.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to retrieve the list of assets.
404 Not Found Site or page not found.

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/pages/page_id/assets?limit=&offset=&class=&sortBy=&sortOrder=&fields=&dateField=&dateFrom=&dateTo=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

page_id
number (required) 

The page ID.

limit
number (optional) Default: 10 

Maximum number of assets to retrieve.

offset
number (optional) Default: 0 

0-indexed offset.

class
string (optional) 

The target asset class to retrieve. Supported values are image, audio, video, file and any values added by plugins. If you want to retrieve multiple classes, specify the values separated by commas.

sortBy
string (optional) Default: created_on 
file_name
Sort by the filename of each asset.
created_by
Sort by the ID of user who created each asset.
created_on
(default) Sort by the created time of each asset.
sortOrder
string (optional) Default: descend 
descend
(default) Return assets in descending order. For sorting by date, it means from newest to oldest.
ascend
Return assets in ascending order. For sorting by date, it means from oldest to newest.
fields
string (optional) 

The field list to retrieve as part of the Assets resource. The list of field names should be separated by commas. If this parameter is not specified, all fields will be returned.

dateField
string (optional) Default: created_on 

Specifies the field name to be used as a date field for filtering. (new in v3)

dateFrom
string (optional) 

The start date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

dateTo
string (optional) 

The end date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults" : 1,
  "items" : [
  {
    "id" : 1,
    "label" : "The Bridge",
    "mimeType" : "image/jpeg",
    "url" : "http://example.com/images/the-bridge.jpg",
    "filename" : "the-bridge",
    "description" : "Taken from over the bridge.",
    "tags" : [
      "boston",
      "bridge",
      "light"
    ],
    "blog" : {
      "id" : 1
    },
    "updatable" : true,
    "modifiedBy" : {
      "id" : 1,
      "displayName" : "Yuji Takayama",
      "userpicUrl" : null
    },
    "modifiedDate" : "2014-10-10T13:13:01+09:00",
    "createdBy" : {
      "id" : 1,
      "displayName" : "Yuji Takayama",
      "userpicUrl" : null
    },
    "cratedDate" : "2014-10-10T13:13:01+09:00",
    "type" : "Image",
    "class" : "image",
    "fileExt" : "jpg",
    "parent" : {
      "id" : null
    },
    "meta" : {
      "height" : 768,
      "width" : 1024,
      "fileSize" : 339773
    }
  ]
}

Retrieve a list of assets that related with tag.
GET/sites/{site_id}/tags/{tag_id}/assets{?limit,offset,class,sortBy,sortOrder,fields,dateField,dateFrom,dateTo}

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to retrieve the list of assets.
404 Not Found Site or tag not found.

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/tags/tag_id/assets?limit=&offset=&class=&sortBy=&sortOrder=&fields=&dateField=&dateFrom=&dateTo=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

tag_id
number (required) 

The tag ID.

limit
number (optional) Default: 10 

Maximum number of assets to retrieve.

offset
number (optional) Default: 0 

0-indexed offset.

class
string (optional) 

The target asset class to retrieve. Supported values are image, audio, video, file and any values added by plugins. If you want to retrieve multiple classes, specify the values separated by commas.

sortBy
string (optional) Default: created_on 
file_name
Sort by the filename of each asset.
created_by
Sort by the ID of user who created each asset.
created_on
(default) Sort by the created time of each asset.
sortOrder
string (optional) Default: descend 
descend
(default) Return assets in descending order. For sorting by date, it means from newest to oldest.
ascend
Return assets in ascending order. For sorting by date, it means from oldest to newest.
fields
string (optional) 

The field list to retrieve as part of the Assets resource. The list of fields should be separated by commas. If this parameter is not specified, all fields will be returned.

dateField
string (optional) Default: created_on 

Specifies the field name to be used as a date field for filtering. (new in v3)

dateFrom
string (optional) 

The start date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

dateTo
string (optional) 

The end date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults" : 1,
  "items" : [
  {
    "id" : 1,
    "label" : "The Bridge",
    "mimeType" : "image/jpeg",
    "url" : "http://example.com/images/the-bridge.jpg",
    "filename" : "the-bridge",
    "description" : "Taken from over the bridge.",
    "tags" : [
      "boston",
      "bridge",
      "light"
    ],
    "blog" : {
      "id" : 1
    },
    "updatable" : true,
    "modifiedBy" : {
      "id" : 1,
      "displayName" : "Yuji Takayama",
      "userpicUrl" : null
    },
    "modifiedDate" : "2014-10-10T13:13:01+09:00",
    "createdBy" : {
      "id" : 1,
      "displayName" : "Yuji Takayama",
      "userpicUrl" : null
    },
    "cratedDate" : "2014-10-10T13:13:01+09:00",
    "type" : "Image",
    "class" : "image",
    "fileExt" : "jpg",
    "parent" : {
      "id" : null
    },
    "meta" : {
      "height" : 768,
      "width" : 1024,
      "fileSize" : 339773
    }
  ]
}

Retrieve a single asset by its ID.
GET/sites/{site_id}/assets/{asset_id}{?fields}

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to retrieve an asset.
404 Not Found Asset (or site) not found.

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/assets/asset_id?fields=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

asset_id
number (required) 

The asset ID.

fields
string (optional) 

The field list to retrieve as part of the Assets resource. The list of field names should be separated by commas. If this parameter is not specified, all fields will be returned.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": 1,
  "label": "The Bridge",
  "mimeType": "image/jpeg",
  "url": "http://example.com/images/the-bridge.jpg",
  "filename": "the-bridge",
  "description": "Taken from over the bridge.",
  "tags": [
    "boston",
    "bridge",
    "light"
  ],
  "blog": {
    "id": 1
  },
  "updatable": true,
  "modifiedBy": {
    "id": 1,
    "displayName": "Yuji Takayama",
    "userpicUrl": null
  },
  "modifiedDate": "2014-10-10T13:13:01+09:00",
  "createdBy": {
    "id": 1,
    "displayName": "Yuji Takayama",
    "userpicUrl": null
  },
  "cratedDate": "2014-10-10T13:13:01+09:00",
  "type": "Image",
  "class": "image",
  "fileExt": "jpg",
  "parent": {
    "id": null
  },
  "meta": {
    "height": 768,
    "width": 1024,
    "fileSize": 339773
  }
}

Update an asset.
PUT/sites/{site_id}/assets/{asset_id}

Authentication required.

This method accepts PUT and POST with __method=PUT.

Status Code

Code Status Description
200 OK No Errors.
401 Unauthorized Authentication required
403 Forbidden Do not have permission to update an asset.
404 Not Found Asset (or site) not found.
405 Method Not Allowed Request method is not ‘PUT’ or ‘POST’ with ‘__method=PUT’

Permissions

  • Manage Assets

Example URI

PUT http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/assets/asset_id
URI Parameters
HideShow
site_id
number (required) 

The site ID.

asset_id
number (required) 

The asset ID.

Request  Assets resource
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Body
asset={
  "url" : "http://localhost/blog/20140917-2/images/0cf61aae.jpg",
  "id" : "1",
  "parent" : null,
  "blog" : {
    "id" : "1"
  },
  "description" : "Over the rainbow.",
  "tags" : [
    "boston",
    "bridge",
    "light",
    "night"
  ],
  "label" : "Night Bridge",
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": 1,
  "label": "Night Bridge",
  "mimeType": "image/jpeg",
  "url": "http://example.com/images/the-bridge.jpg",
  "filename": "the-bridge",
  "description": "Over the rainbow.",
  "tags": [
    "boston",
    "bridge",
    "light",
    "night"
  ],
  "blog": {
    "id": 1
  },
  "updatable": true,
  "modifiedBy": {
    "id": 1,
    "displayName": "Yuji Takayama",
    "userpicUrl": null
  },
  "modifiedDate": "2014-10-10T14:13:01+09:00",
  "createdBy": {
    "id": 1,
    "displayName": "Yuji Takayama",
    "userpicUrl": null
  },
  "cratedDate": "2014-10-10T13:13:01+09:00",
  "type": "Image",
  "class": "image",
  "fileExt": "jpg",
  "parent": {
    "id": null
  },
  "meta": {
    "height": 768,
    "width": 1024,
    "fileSize": 339773
  }
}

Delete an asset.
DELETE/sites/{site_id}/assets/{asset_id}

Authentication required.

This method accepts DELETE and POST with __method=DELETE.

Status Code

Code Status Description
200 OK No Errors.
401 Unauthorized Authentication required
403 Forbidden Do not have permission to delete an asset.
404 Not Found Asset (or site) not found.
405 Method Not Allowed Request method is not ‘DELETE’ or ‘POST’ with ‘__method=DELETE’

Permissions

  • Manage Assets

Example URI

DELETE http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/assets/asset_id
URI Parameters
HideShow
site_id
number (required) 

The site ID.

asset_id
number (required) 

The asset ID.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": 1,
  "label": "The Bridge",
  "mimeType": "image/jpeg",
  "url": "http://example.com/images/the-bridge.jpg",
  "filename": "the-bridge",
  "description": "Taken from over the bridge.",
  "tags": [
    "boston",
    "bridge",
    "light"
  ],
  "blog": {
    "id": 1
  },
  "updatable": false,
  "modifiedBy": {
    "id": 1,
    "displayName": "Yuji Takayama",
    "userpicUrl": null
  },
  "modifiedDate": "2014-10-10T13:13:01+09:00",
  "createdBy": {
    "id": 1,
    "displayName": "Yuji Takayama",
    "userpicUrl": null
  },
  "cratedDate": "2014-10-10T13:13:01+09:00",
  "type": "Image",
  "class": "image",
  "fileExt": "jpg",
  "parent": {
    "id": null
  },
  "meta": {
    "height": 768,
    "width": 1024,
    "fileSize": 339773
  }
}

Thumbnail

Get thumbnail image for an asset.
GET/sites/{site_id}/assets/{asset_id}/thumbnail{?width,height,scale,square}

This endpoint requires one of parameter ‘width’ or ‘height’ or ‘scale’ Also, cannot use these parameters at same time.

Status Code

Code Status Description
200 OK No Errors.
400 Bad Request An asset does not support to generate thumbnail file.
403 Forbidden Do not have permission to update an asset.
404 Not Found Asset (or site) not found.

Permissions

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/assets/asset_id/thumbnail?width=&height=&scale=&square=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

asset_id
number (required) 

The asset ID.

width
number (optional) 

The width of the thumbnail to generate. If this is the only parameter specified then the thumbnail’s width will be scaled proportionally to the height. When a value longer than the original image is specified, it will be ignored.

height
number (optional) 

The height of the thumbnail to generate. If this is the only parameter specified then the thumbnail’s height will be scaled proportionally to the width. When both of height and width are specified, the longer side of the original image will be processed, and the lesser side will be scaled proportionally.

scale
string (optional) 

The percentage by which to reduce or increase the size of the current asset.

square
boolean (optional) 

If set to true then the thumbnail generated will be square, where the length of each side of the square will be equal to the shortest side of the image.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "height": 200,
  "width": 200,
  "url": "http://example.com/assets_c/2014/10/the-bridge-200x200-1.jpg"
}

Categories

This is the Categories resource.

Property Name Type Data Type Database Column Private Read Only Description Version
archiveLink value string Y The category archive URL of this category. If “Category” archive mapping is not configured, this value will be null. v2
basename value string mt_category_category_basename The basename of this category. v1
blog object - The blog of this category. v1
blog.id value number mt_category.category_blog_id Y The ID of the blog that contains this category. v1
class value string mt_category.category_class Y The object class for this category. v1
createdBy Object - Y The user who created this category. v2
createdBy.displayName value string Y The display name of the user who created this category. v2
createdBy.id value number mt_category.category_created_by Y Y The ID of the user who created this category. v2
createdBy.userpicUrl value string Y The URL of created user’s userpic. The userpic will be made by UserpicThumbnailSize and UserpicAllowRect settings. If user does not set own userpic, empty string will be returned. v2
createdDate value iso 8601 datetime mt_ctegory.category_created_on Y The created time for this category. v2
customFields ARRAY - The list of customfields data for this category. v1
customFields.basename value string mt_field.field_basename The basename of this customfield. v1
customFields.value value string The value of this customfield. v1
description value string mt_category.category_description Y The description of this category. v1
id value number mt_category.category_id Y The ID of this category. v1
label value string mt_category.category_label Y The label of this category. v1
modifiedBy Object - Y The user who last modified this category. v2
modifiedBy.id value number mt_category.category_modified_by Y Y The ID of user who last modified category. v2
modifiedBy.displayName value string Y The display name of user who last modified category. v2
modifiedBy.userpicUrl value string Y The URL of last modified user’s userpic. The userpic will be made by UserpicThumbnailSize and UserpicAllowRect settings. If user does not set own userpic, empty string will be returned. v2
modifiedDate value iso 8601 datetime mt_category.category_modified_on Y The last modified time for this category. v2
parent value number mt_category.cateogry_parent The ID of the parent category for this category. This field can be updated from v2. v1
updatable value boolean Y
true
The user who accessed can update this category.
false
The user who accessed cannot update this category.
 v2

{ “parent” : “0”, “createdBy” : { “id” : 1 “userpicUrl” : “/mt-static/support/assets_c/userpics/userpic-1-100x100.png”, “displayName” : “Yuji Takayama” }, “updatable” : false, “blog” : { “id” : “22” }, “description” : “This category includes news articles”, “basename” : “news”, “archiveLink” : “http://example.com/news/index.html”, “id” : 23, “class” : “category”, “label” : “News”, “createdDate” : “2014-11-05T12:48:27+09:00”, “modifiedDate” : “2014-11-05T12:52:51+09:00”, “modifiedBy” : { “id” : 1 “userpicUrl” : “/mt-static/support/assets_c/userpics/userpic-1-100x100.png”, “displayName” : “Yuji Takayama” }, “customFields” : [ { “basename” : “bannerimage”, “value” : "<form mt:asset-id=“3” class=“mt-enclosure mt-enclosure-image” style=“display: inline;”><a href=“http://localhost/blog/20141105-1/images/4db95178.png”>4db95178.png" }, { “basename” : “address”, “value” : “” }

Categories

Retrieve a list of categories
GET/sites/{site_id}/categories{?search,searchFields,limit,offset,sortBy,sortOrder,fields,top,includeIds,excludeIds,dateField,dateFrom,dateTo}

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to retrieve the list of categories.
404 Not Found Site not found.

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/categories?search=&searchFields=&limit=&offset=&sortBy=&sortOrder=&fields=&top=&includeIds=&excludeIds=&dateField=&dateFrom=&dateTo=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

search
string (optional) 

Search query.

searchFields
string (optional) Default: label,basename 

The comma separated list of field names to search.

limit
number (optional) Default: 10 

Maximum number of categories to retrieve.

offset
number (optional) Default: 0 

0-indexed offset.

sortBy
string (optional) Default: user_custom 
user_custom
Sort order you specified on the Manage Categories screen.
created_by
Sort by the ID of user who created each category.
id
Sort by the ID of each category.
basename
Sort by the basename of each category.
label
Sort by the label of each category.
sortOrder
string (optional) Default: descend 
descend
(default) Return categories in descending order.
ascend
Return categories in ascending order.
fields
string (optional) 

The field list to retrieve as part of the Categories resource. The list of field names should be separated by commas. If this parameter is not specified, all fields will be returned.

top
number (optional) Default: 0 

If set to 1, retrieves only top level categories. New in v2

includeIds
string (optional) 

The comma separated list of category IDs to include in result.

excludeIds
string (optional) 

The comma separated list of category IDs to exclude from result.

dateField
string (optional) Default: created_on 

Specifies the field name to be used as a date field for filtering. (new in v3)

dateFrom
string (optional) 

The start date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

dateTo
string (optional) 

The end date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults" : "1",
  "items" : [
    {
    "basename" : "news",
    "parent" : "0",
    "archiveLink" : "http://example.com/news/index.html",
    "updatable" : false,
    "label" : "News",
    "class" : "category",
    "id" : 2,
    "blog" : {
      "id" : "1"
    },
    "description" : null
  ]
}

Retrieve a list of categories that related with entry.
GET/sites/{site_id}/entries/{entry_id}/categories{?search,searchFields,limit,offset,sortBy,sortOrder,fields,type,includeIds,excludeIds,top,dateField,dateFrom,dateTo}

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to retrieve the list of categories.
404 Not Found Site or Entry not found.

Permissions

  • edit_entry
    • If want to retrieve the non-published entry’s categories.

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/entries/entry_id/categories?search=&searchFields=&limit=&offset=&sortBy=&sortOrder=&fields=&type=&includeIds=&excludeIds=&top=&dateField=&dateFrom=&dateTo=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

entry_id
number (required) 

The entry ID.

search
string (optional) 

Search query.

searchFields
string (optional) Default: label,basename 

The comma separated list of field names to search.

limit
number (optional) Default: 10 

Maximum number of categories to retrieve.

offset
number (optional) Default: 0 

0-indexed offset.

sortBy
string (optional) Default: user_custom 
user_custom
Sort order you specified on the Manage Categories screen.
created_by
Sort by the ID of user who created each category.
id
Sort by the ID of each category.
basename
Sort by the basename of each category.
label
Sort by the label of each category.
sortOrder
string (optional) Default: descend 
descend
(default) Return categories in descending order.
ascend
Return categories in ascending order.
fields
string (optional) 

The field list to retrieve as part of the Categories resource. The list of field names should be separated by commas. If this parameter is not specified, all fields will be returned.

top
number (optional) Default: 0 

If set to 1, retrieves only top level categories. New in v2

includeIds
string (optional) 

The comma separated list of category IDs to include in result.

excludeIds
string (optional) 

The comma separated list of category IDs to exclude from result.

type
string (optional) 
primary
Retrieve primary category only
secondary
Retrieve secondary categories only
dateField
string (optional) Default: created_on 

Specifies the field name to be used as a date field for filtering. (new in v3)

dateFrom
string (optional) 

The start date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

dateTo
string (optional) 

The end date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults" : "1",
  "items" : [
    {
    "basename" : "news",
    "parent" : "0",
    "archiveLink" : "http://example.com/news/index.html",
    "updatable" : false,
    "label" : "News",
    "class" : "category",
    "id" : 2,
    "blog" : {
      "id" : "1"
    },
    "description" : null
  ]
}

Retrieve a list of parent categories.
GET/sites/{site_id}/categories/{category_id}/parents{?maxDepth,includeCurrent,dateField,dateFrom,dateTo}

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to retrieve the list of categories.
404 Not Found Site or Category not found.

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/categories/category_id/parents?maxDepth=&includeCurrent=&dateField=&dateFrom=&dateTo=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

category_id
number (required) 

The category ID.

maxDepth
number (optional) Default: 0 

The depth of retrieving parent categories.

includeCurrent
number (optional) Default: 0 
1
The list does not include current category.
0
The list includes current category.
dateField
string (optional) Default: created_on 

Specifies the field name to be used as a date field for filtering. (new in v3)

dateFrom
string (optional) 

The start date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

dateTo
string (optional) 

The end date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults" : "1",
  "items" : [
    {
    "basename" : "news",
    "parent" : "0",
    "archiveLink" : "http://example.com/news/index.html",
    "updatable" : false,
    "label" : "News",
    "class" : "category",
    "id" : 2,
    "blog" : {
      "id" : "1"
    },
    "description" : null
  ]
}

Retrieve a list of siblings categories.
GET/sites/{site_id}/categories/{category_id}/siblings{?search,searchFields,limit,offset,sortBy,sortOrder,fields,top,includeIds,excludeIds,dateField,dateFrom,dateTo}

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to retrieve the list of categories.
404 Not Found Site or Category not found.

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/categories/category_id/siblings?search=&searchFields=&limit=&offset=&sortBy=&sortOrder=&fields=&top=&includeIds=&excludeIds=&dateField=&dateFrom=&dateTo=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

category_id
number (required) 

The category ID.

search
string (optional) 

Search query.

searchFields
string (optional) Default: label,basename 

The comma separated list of field names to search.

limit
number (optional) Default: 10 

Maximum number of categories to retrieve.

offset
number (optional) Default: 0 

0-indexed offset.

sortBy
string (optional) Default: user_custom 
user_custom
Sort order you specified on the Manage Categories screen.
created_by
Sort by the ID of user who created each category.
id
Sort by the ID of each category.
basename
Sort by the basename of each category.
label
Sort by the label of each category.
sortOrder
string (optional) Default: descend 
descend
(default) Return categories in descending order.
ascend
Return categories in ascending order.
fields
string (optional) 

The field list to retrieve as part of the Categories resource. The list of field names should be separated by commas. If this parameter is not specified, all fields will be returned.

top
number (optional) Default: 0 

If set to 1, retrieves only top level categories. New in v2

includeIds
string (optional) 

The comma separated list of category IDs to include in result.

excludeIds
string (optional) 

The comma separated list of category IDs to exclude from result.

dateField
string (optional) Default: created_on 

Specifies the field name to be used as a date field for filtering. (new in v3)

dateFrom
string (optional) 

The start date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

dateTo
string (optional) 

The end date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults" : "1",
  "items" : [
    {
    "basename" : "news",
    "parent" : "0",
    "archiveLink" : "http://example.com/news/index.html",
    "updatable" : false,
    "label" : "News",
    "class" : "category",
    "id" : 2,
    "blog" : {
      "id" : "1"
    },
    "description" : null
  ]
}

Retrieve a list of child categories.
GET/sites/{site_id}/categories/{category_id}/children{?maxDepth,includeCurrent,dateField,dateFrom,dateTo}

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to retrieve the list of categories.
404 Not Found Site or Category not found.

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/categories/category_id/children?maxDepth=&includeCurrent=&dateField=&dateFrom=&dateTo=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

category_id
number (required) 

The category ID.

maxDepth
number (optional) Default: 0 

The depth of retrieving parent categories.

includeCurrent
number (optional) Default: 0 
0
The list does not include current category.
1
The list includes current category.
dateField
string (optional) Default: created_on 

Specifies the field name to be used as a date field for filtering. (new in v3)

dateFrom
string (optional) 

The start date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

dateTo
string (optional) 

The end date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults" : "1",
  "items" : [
    {
    "basename" : "news",
    "parent" : "0",
    "archiveLink" : "http://example.com/news/index.html",
    "updatable" : false,
    "label" : "News",
    "class" : "category",
    "id" : 2,
    "blog" : {
      "id" : "1"
    },
    "description" : null
  ]
}

Create a new category.
POST/sites/{site_id}/categories

Authentication required.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to create a new category.
404 Not Found Site not found.

Permission

  • Manage Categories

Request Body Parameters

Name Type Required Default Description
category Object Yes Single Categories resource

Example URI

POST http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/categories
URI Parameters
HideShow
site_id
number (required) 

The site ID.

Request  Assets resource
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Body
category={"basename" : "news","parent" : "0","label" : "News","description" : null}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults" : "1",
  "items" : [
    {
    "basename" : "news",
    "parent" : "0",
    "archiveLink" : "http://example.com/news/index.html",
    "updatable" : false,
    "label" : "News",
    "class" : "category",
    "id" : 2,
    "blog" : {
      "id" : "1"
    },
    "description" : null
  ]
}

Retrieve a single category by its ID.
GET/sites/{site_id}/categories/{category_id}{?fields}

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to retrieve an category.
404 Not Found Category or site not found.

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/categories/category_id?fields=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

category_id
number (required) 

The category ID.

fields
string (optional) 

The field list to retrieve as part of the Categories resource. The list of field names should be separated by commas. If this parameter is not specified, all fields will be returned.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "basename": "news",
  "parent": "0",
  "archiveLink": "http://example.com/news/index.html",
  "updatable": false,
  "label": "News",
  "class": "category",
  "id": 2,
  "blog": {
    "id": "1"
  },
  "description": null
}

Update an existing category.
PUT/sites/{site_id}/categories/{category_id}

Authentication required.

This method accepts PUT and POST with __method=PUT.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to update a category.
404 Not Found Site or Category not found.

Permission

  • Manage Categories

Request Body Parameters

Name Type Required Default Description
category Object Yes Single Categories resource

Example URI

PUT http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/categories/category_id
URI Parameters
HideShow
site_id
number (required) 

The site ID.

category_id
number (required) 

The category ID.

Request  Categories resource
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Body
category={"basename" : "news","parent" : "0","archiveLink" : "http://example.com/news/index.html","updatable" : false,"label" : "News","class" : "category","id" : "1","blog" : {"id" : "1"},"description" : null,"customFields" : [{"basename" : "bannerImage","value" : "http://example.com/images/banner.jpg"}]}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "basename": "news",
  "parent": "0",
  "archiveLink": "http://example.com/news/index.html",
  "updatable": false,
  "label": "News",
  "class": "category",
  "id": 2,
  "blog": {
    "id": "1"
  },
  "description": null
}

Delete an existing category.
DELETE/sites/{site_id}/categories/{category_id}

Authentication required.

This method accepts DELETE and POST with __method=DELETE.

This method returns deleted Category resource.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to delete a category.
404 Not Found Site or Category not found.

Permission

  • Manage Categories

Example URI

DELETE http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/categories/category_id
URI Parameters
HideShow
site_id
number (required) 

The site ID.

category_id
number (required) 

The category ID.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "basename": "news",
  "parent": "0",
  "archiveLink": "http://example.com/news/index.html",
  "updatable": false,
  "label": "News",
  "class": "category",
  "id": 2,
  "blog": {
    "id": "1"
  },
  "description": null
}

Rearrange existing categories in a new order.
POST/sites/{site_id}/categories/permutate

Authentication required.

This method returns rearranged Categories resource.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to delete a category.
404 Not Found Site not found.

Permission

  • Manage Categories

Request Body Parameters

Name Type Required Default Description
categories ARRAY Yes Array of Categories resource that were rearranged.

Example URI

POST http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/categories/permutate
URI Parameters
HideShow
site_id
number (required) 

The site ID.

Request  Assets resource
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Body
category=[{"basename" : "news","parent" : "0","archiveLink" : "http://example.com/news/index.html","updatable" : false,"label" : "News","class" : "category","id" : "1","blog" : {"id" : "1"},"description" : null,"customFields" : [{"basename" : "bannerImage","value" : "http://example.com/images/banner.jpg"}]}]
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "basename": "news",
    "parent": "0",
    "archiveLink": "http://example.com/news/index.html",
    "updatable": false,
    "label": "News",
    "class": "category",
    "id": 2,
    "blog": {
      "id": "1"
    },
    "description": null
  }
]

Comments

This is the Comments resource.

Property Name Type Data Type Database Column Private Read Only Description Version
author Object - Y The commenter of this comment. v1
author.id value number mt_comment.comment_commenter_id Y Y The ID of this commenter. If commenter is not a registerd user, this field is empty. v1
author.displayName value string mt_comment.comment_author Y The display name of this commenter. v1
author.userpicUrl value number Y The URL of this commenter’s userpic. The userpic will be made by UserpicThumbnailSize and UserpicAllowRect settings. If a commenter is not a registered user or a commenter does not set own userpic, will be returned empty string. v1
blog Object Y The blog of this comment. v1
blog.id value number mt_comment.comment_blog_id Y The ID of the blog that contains this comment. v1
body value string mt_comment.comment_text The contents of this comment. v1
createdBy Object - Y The created user of this comment. In most cases, this is alias of author. v2
createdBy.id value number mt_comment.comment_created_by Y Y The ID of created user. v2
createdBy.displayName value string Y The display name of created user. v2
createdBy.userpicUrl value string Y The URL of created user’s userpic. The userpic will be made by UserpicThumbnailSize and UserpicAllowRect settings. If user does not set own userpic, will be returned empty string. v2
createdDate value iso 8601 datetime mt_comment.comment_created_on Y The created time for this comment. v2
customFields ARRAY - The list of customfields data for this category. v1
customFields.basename value string mt_field.field_basename The basename of this customfield. v1
customFields.value value string The value of this customfield. v1
date value iso 8601 datetime mt_comment.comment_created_on Y The creation time for this comment. This property is marked as deprecated in v2.0. v1
entry Object - Y The container entry of this comment. v1
entry.id value number mt_comment.comment_entry_id Y The ID of the entry that contains this comment. v1
id value number mt_comment.comment_id Y The ID of this comment. v1
link value string Y The permalink for this comment. v1
modifiedBy Object - Y The last modified user of this comment. v2
modifiedBy.displayName value string Y The display name of last modified user. v2
modifiedBy.id value number mt_comment.comment_modified_by Y Y The ID of last modified user. v2
modifiedBy.userpicUrl value string Y The URL of last modified user’s userpic. The userpic will be made by UserpicThumbnailSize and UserpicAllowRect settings. If user does not set own userpic, will be returned empty string. v2
modifiedDate value iso 8601 datetime mt_comment.comment_modified_on Y The last modified time for this comment. v2
parent value number mt_comment.comment_parent_id The ID of the parent of this comment. If this comment is not a reply, will be returned as null. v1
status value string The publishing status of this comment.
Approved
This comment has been approved.
In the database, comment_visible = 1 and comment_junk_status = 1.
Pending
This comment has not been approved.
In the database, comment_visible = 0 and comment_junk_status = 1.
Spam
This comment has been marked as Spam.
In the database, comment_visible = 0 and comment_junk_status = -1.
 v1
updatable value boolean Y
true
The user who accessed can update this comment.
false
The user who accessed cannot update this comment.
 v1

{ “link” : "http://example.com/blog/2014/11/hello-movable-type.html#comment-1", “parent” : null, “entry” : { “id” : “45” }, “createdBy” : { “id” : 2 “userpicUrl” : null, “displayName” : “Ichiro Aikawa” }, “status” : “Approved”, “date” : “2014-11-05T14:41:39+09:00”, “updatable” : false, “blog” : { “id” : “22” }, “author” : { “id” : 2 “userpicUrl” : null, “displayName” : “Ichiro Aikawa” }, “body” : "

Hi, congrats!

", “createdDate” : “2014-11-05T14:41:39+09:00”, “id” : 1, “modifiedDate” : “2014-11-05T14:41:39+09:00”, “customFields” : [] }

Comments

Retrieve a list of comments.
GET/sites/{site_id}/comments{?search,searchFields,limit,offset,sortBy,sortOrder,fields,includeIds,excludeIds,status,entryStatus,dateField,dateFrom,dateTo}

Authorization is required if want to include unpublished comments.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to retrieve the list of comments.
404 Not Found Site not found.

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/comments?search=&searchFields=&limit=&offset=&sortBy=&sortOrder=&fields=&includeIds=&excludeIds=&status=&entryStatus=&dateField=&dateFrom=&dateTo=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

search
string (optional) 

Search query.

searchFields
string (optional) Default: body 

The comma separated field name list to search.

limit
number (optional) Default: 10 

Maximum number of comments to retrieve.

offset
number (optional) Default: 0 

0-indexed offset.

sortBy
string (optional) Default: id 

The field name for sort.

sortOrder
string (optional) Default: descend 
descend
(default) Return comments in descending order.
ascend
Return comments in ascending order.
fields
string (optional) 

The field list to retrieve as part of the Comments resource. That list should be separated by comma. If this parameter is not specified, All fields will be returned.

includeIds
string (optional) 

The comma separated ID list of comments to include to result.

excludeIds
string (optional) 

The comma separated ID list of comments to exclude from result.

status
string (optional) 

Filter by status.

Approved
comment_visible is 1 and comment_junk_status is 1.
Pending
comment_visible is 0 and comment_junk_status is 1.
Spam
comment_junk_status is -1.

entryStatus
string (optional) 

Filter by container entry’s status.

Draft
entry_status is 1.
Publish
entry_status is 2.
Review
entry_status is 3.
Future
entry_status is 4.
Spam
entry_status is 5.

dateField
string (optional) Default: created_on 

Specifies the field name to be used as a date field for filtering. (new in v3)

dateFrom
string (optional) 

The start date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

dateTo
string (optional) 

The end date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults" : "1",
  "items" : [
    {
      "link" : "http://example.com/blog/2014/11/hello-movable-type.html#comment-1",
      "parent" : null,
      "entry" : {
        "id" : "45"
      },
      "createdBy" : {
        "id" : 2
        "userpicUrl" : null,
        "displayName" : "Ichiro Aikawa"
      },
      "status" : "Approved",
      "date" : "2014-11-05T14:41:39+09:00",
      "updatable" : false,
      "blog" : {
        "id" : "22"
      },
      "author" : {
        "id" : 2
        "userpicUrl" : null,
        "displayName" : "Ichiro Aikawa"
      },
      "body" : "<p>Hi, congrats!</p>",
      "createdDate" : "2014-11-05T14:41:39+09:00",
      "id" : 1,
      "modifiedDate" : "2014-11-05T14:41:39+09:00",
      "customFields" : []
    }
  ]
}

Retrieve a list of comments that related with entry.
GET/sites/{site_id}/entries/{entry_id}/comments{?search,searchFields,limit,offset,sortBy,sortOrder,fields,includeIds,excludeIds,status,dateField,dateFrom,dateTo}

Authorization is required if want to include unpublished comments.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to retrieve the list of comments.
404 Not Found Site or Entry not found.

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/entries/entry_id/comments?search=&searchFields=&limit=&offset=&sortBy=&sortOrder=&fields=&includeIds=&excludeIds=&status=&dateField=&dateFrom=&dateTo=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

entry_id
number (required) 

The entry ID.

search
string (optional) 

Search query.

searchFields
string (optional) Default: body 

The comma separated field name list to search.

limit
number (optional) Default: 10 

Maximum number of comments to retrieve.

offset
number (optional) Default: 0 

0-indexed offset.

sortBy
string (optional) Default: id 

The field name for sort.

sortOrder
string (optional) Default: descend 
descend
(default) Return comments in descending order.
ascend
Return comments in ascending order.
fields
string (optional) 

The field list to retrieve as part of the Comments resource. That list should be separated by comma. If this parameter is not specified, All fields will be returned.

includeIds
string (optional) 

The comma separated ID list of comments to include to result.

excludeIds
string (optional) 

The comma separated ID list of comments to exclude from result.

status
string (optional) 

Filter by status.

Approved
comment_visible is 1 and comment_junk_status is 1.
Pending
comment_visible is 0 and comment_junk_status is 1.
Spam
comment_junk_status is -1.

dateField
string (optional) Default: created_on 

Specifies the field name to be used as a date field for filtering. (new in v3)

dateFrom
string (optional) 

The start date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

dateTo
string (optional) 

The end date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults" : "1",
  "items" : [
    {
      "link" : "http://example.com/blog/2014/11/hello-movable-type.html#comment-1",
      "parent" : null,
      "entry" : {
        "id" : "45"
      },
      "createdBy" : {
        "id" : 2
        "userpicUrl" : null,
        "displayName" : "Ichiro Aikawa"
      },
      "status" : "Approved",
      "date" : "2014-11-05T14:41:39+09:00",
      "updatable" : false,
      "blog" : {
        "id" : "22"
      },
      "author" : {
        "id" : 2
        "userpicUrl" : null,
        "displayName" : "Ichiro Aikawa"
      },
      "body" : "<p>Hi, congrats!</p>",
      "createdDate" : "2014-11-05T14:41:39+09:00",
      "id" : 1,
      "modifiedDate" : "2014-11-05T14:41:39+09:00",
      "customFields" : []
    }
  ]
}

Retrieve a list of comments that related with page.
GET/sites/{site_id}/pages/{page_id}/comments{?search,searchFields,limit,offset,sortBy,sortOrder,fields,includeIds,excludeIds,status,dateField,dateFrom,dateTo}

Authentication is required if want to include unpublished comments.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to retrieve the list of comments.
404 Not Found Site or Page not found.

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/pages/page_id/comments?search=&searchFields=&limit=&offset=&sortBy=&sortOrder=&fields=&includeIds=&excludeIds=&status=&dateField=&dateFrom=&dateTo=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

page_id
number (required) 

The page ID.

search
string (optional) 

Search query.

searchFields
string (optional) Default: body 

The comma separated field name list to search.

limit
number (optional) Default: 10 

Maximum number of comments to retrieve.

offset
number (optional) Default: 0 

0-indexed offset.

sortBy
string (optional) Default: id 

The field name for sort.

sortOrder
string (optional) Default: descend 
descend
(default) Return comments in descending order.
ascend
Return comments in ascending order.
fields
string (optional) 

The field list to retrieve as part of the Comments resource. That list should be separated by comma. If this parameter is not specified, All fields will be returned.

includeIds
string (optional) 

The comma separated ID list of comments to include to result.

excludeIds
string (optional) 

The comma separated ID list of comments to exclude from result.

status
string (optional) 

Filter by status.

Approved
comment_visible is 1 and comment_junk_status is 1.
Pending
comment_visible is 0 and comment_junk_status is 1.
Spam
comment_junk_status is -1.

dateField
string (optional) Default: created_on 

Specifies the field name to be used as a date field for filtering. (new in v3)

dateFrom
string (optional) 

The start date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

dateTo
string (optional) 

The end date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults" : "1",
  "items" : [
    {
      "link" : "http://example.com/blog/2014/11/hello-movable-type.html#comment-1",
      "parent" : null,
      "entry" : {
        "id" : "45"
      },
      "createdBy" : {
        "id" : 2
        "userpicUrl" : null,
        "displayName" : "Ichiro Aikawa"
      },
      "status" : "Approved",
      "date" : "2014-11-05T14:41:39+09:00",
      "updatable" : false,
      "blog" : {
        "id" : "22"
      },
      "author" : {
        "id" : 2
        "userpicUrl" : null,
        "displayName" : "Ichiro Aikawa"
      },
      "body" : "<p>Hi, congrats!</p>",
      "createdDate" : "2014-11-05T14:41:39+09:00",
      "id" : 1,
      "modifiedDate" : "2014-11-05T14:41:39+09:00",
      "customFields" : []
    }
  ]
}

Create a new comment for entry.
POST/sites/{site_id}/entries/{entry_id}/comments

Authentication required.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to create a new coment.
404 Not Found Site or Entry not found.

Permission

  • Comment

Request Body Parameters

Name Type Required Default Description
comment Object Yes Single Comments resource

Example URI

POST http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/entries/entry_id/comments
URI Parameters
HideShow
site_id
number (required) 

The site ID.

entry_id
number (required) 

The entry ID.

Request  Assets resource
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Body
comment={"body" : "This is a test comment.\nHe he he"}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "link" : "http://example.com/blog/2014/11/hello-movable-type.html#comment-1",
  "parent" : null,
  "entry" : {
    "id" : "45"
  },
  "createdBy" : {
    "id" : 2
    "userpicUrl" : null,
    "displayName" : "Ichiro Aikawa"
  },
  "status" : "Approved",
  "date" : "2014-11-05T14:41:39+09:00",
  "updatable" : false,
  "blog" : {
    "id" : "22"
  },
  "author" : {
    "id" : 2
    "userpicUrl" : null,
    "displayName" : "Ichiro Aikawa"
  },
  "body" : "<p>Hi, congrats!</p>",
  "createdDate" : "2014-11-05T14:41:39+09:00",
  "id" : 1,
  "modifiedDate" : "2014-11-05T14:41:39+09:00",
  "customFields" : []
}

Create a new comment for page.
POST/sites/{site_id}/pages/{page_id}/comments

Authentication required.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to create a new coment.
404 Not Found Site or Page not found.

Permission

  • Comment

Request Body Parameters

Name Type Required Default Description
comment Object Yes Single Comments resource

Example URI

POST http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/pages/page_id/comments
URI Parameters
HideShow
site_id
number (required) 

The site ID.

page_id
number (required) 

The page ID.

Request  Assets resource
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Body
comment={"body" : "This is a test comment.\nHe he he"}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "link" : "http://example.com/blog/2014/11/hello-movable-type.html#comment-1",
  "parent" : null,
  "entry" : {
    "id" : "45"
  },
  "createdBy" : {
    "id" : 2
    "userpicUrl" : null,
    "displayName" : "Ichiro Aikawa"
  },
  "status" : "Approved",
  "date" : "2014-11-05T14:41:39+09:00",
  "updatable" : false,
  "blog" : {
    "id" : "22"
  },
  "author" : {
    "id" : 2
    "userpicUrl" : null,
    "displayName" : "Ichiro Aikawa"
  },
  "body" : "<p>Hi, congrats!</p>",
  "createdDate" : "2014-11-05T14:41:39+09:00",
  "id" : 1,
  "modifiedDate" : "2014-11-05T14:41:39+09:00",
  "customFields" : []
}

Reply to comment
POST/sites/{site_id}/comments/{comment_id}/replies

Authentication required.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to reply coment.
404 Not Found Site or Comment not found.

Permission

  • Comment

Request Body Parameters

Name Type Required Default Description
comment Object Yes Single Comments resource

Example URI

POST http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/comments/comment_id/replies
URI Parameters
HideShow
site_id
number (required) 

The site ID.

comment_id
number (required) 

The page ID.

Request  Assets resource
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Body
comment={"body" : "This is a test comment.\nHe he he"}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "link" : "http://example.com/blog/2014/11/hello-movable-type.html#comment-1",
  "parent" : null,
  "entry" : {
    "id" : "45"
  },
  "createdBy" : {
    "id" : 2
    "userpicUrl" : null,
    "displayName" : "Ichiro Aikawa"
  },
  "status" : "Approved",
  "date" : "2014-11-05T14:41:39+09:00",
  "updatable" : false,
  "blog" : {
    "id" : "22"
  },
  "author" : {
    "id" : 2
    "userpicUrl" : null,
    "displayName" : "Ichiro Aikawa"
  },
  "body" : "<p>Hi, congrats!</p>",
  "createdDate" : "2014-11-05T14:41:39+09:00",
  "id" : 1,
  "modifiedDate" : "2014-11-05T14:41:39+09:00",
  "customFields" : []
}

Retrieve a single comment by its ID.
GET/sites/{site_id}/comments/{comment_id}{?fields}

Authorization is required if the comment status is “unpublished”.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to retrieve the requested comment.
404 Not Found Site or Comment not found.

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/comments/comment_id?fields=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

comment_id
number (required) 

The comment ID.

fields
string (optional) 

The field list to retrieve as part of the Comments resource. That list should be separated by comma. If this parameter is not specified, All fields will be returned.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "link" : "http://example.com/blog/2014/11/hello-movable-type.html#comment-1",
  "parent" : null,
  "entry" : {
    "id" : "45"
  },
  "createdBy" : {
    "id" : 2
    "userpicUrl" : null,
    "displayName" : "Ichiro Aikawa"
  },
  "status" : "Approved",
  "date" : "2014-11-05T14:41:39+09:00",
  "updatable" : false,
  "blog" : {
    "id" : "22"
  },
  "author" : {
    "id" : 2
    "userpicUrl" : null,
    "displayName" : "Ichiro Aikawa"
  },
  "body" : "<p>Hi, congrats!</p>",
  "createdDate" : "2014-11-05T14:41:39+09:00",
  "id" : 1,
  "modifiedDate" : "2014-11-05T14:41:39+09:00",
  "customFields" : []
}

Update an exsiting comment.
PUT/sites/{site_id}/comments/{comment_id}

Authentication required.

This method accepts PUT and POST with __method=PUT.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to update the requested comment.
404 Not Found Site or Comment not found.

Example URI

PUT http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/comments/comment_id
URI Parameters
HideShow
site_id
number (required) 

The site ID.

comment_id
number (required) 

The comment ID.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "link" : "http://example.com/blog/2014/11/hello-movable-type.html#comment-1",
  "parent" : null,
  "entry" : {
    "id" : "45"
  },
  "createdBy" : {
    "id" : 2
    "userpicUrl" : null,
    "displayName" : "Ichiro Aikawa"
  },
  "status" : "Approved",
  "date" : "2014-11-05T14:41:39+09:00",
  "updatable" : false,
  "blog" : {
    "id" : "22"
  },
  "author" : {
    "id" : 2
    "userpicUrl" : null,
    "displayName" : "Ichiro Aikawa"
  },
  "body" : "<p>Hi, congrats!</p>",
  "createdDate" : "2014-11-05T14:41:39+09:00",
  "id" : 1,
  "modifiedDate" : "2014-11-05T14:41:39+09:00",
  "customFields" : []
}

Delete an existing comment.
DELETE/sites/{site_id}/comments/{comment_id}

Authentication required.

This method accepts PUT and POST with __method=DELETE.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to delete the requested comment.
404 Not Found Site or Comment not found.

Example URI

DELETE http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/comments/comment_id
URI Parameters
HideShow
site_id
number (required) 

The site ID.

comment_id
number (required) 

The comment ID.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "link" : "http://example.com/blog/2014/11/hello-movable-type.html#comment-1",
  "parent" : null,
  "entry" : {
    "id" : "45"
  },
  "createdBy" : {
    "id" : 2
    "userpicUrl" : null,
    "displayName" : "Ichiro Aikawa"
  },
  "status" : "Approved",
  "date" : "2014-11-05T14:41:39+09:00",
  "updatable" : false,
  "blog" : {
    "id" : "22"
  },
  "author" : {
    "id" : 2
    "userpicUrl" : null,
    "displayName" : "Ichiro Aikawa"
  },
  "body" : "<p>Hi, congrats!</p>",
  "createdDate" : "2014-11-05T14:41:39+09:00",
  "id" : 1,
  "modifiedDate" : "2014-11-05T14:41:39+09:00",
  "customFields" : []
}

Entries

This is the Entries resource.

Property Name Type Data Type Database Column Private Read Only Description Version
allowComments value boolean mt_entry.entry_allow_comments
false
This entry does not accepts comments. In the database, this value is 0.
true
This entry accepts comments. In the database, this value is 1.
 v1
allowTrackbacks value boolean mt_entry.entry_allow_pings
false
This entry does not accepts trackbacks. In the database, this value is 0.
true
This entry accepts trackbacks. In the database, this value is 1.
 v1
assets ARRAY Assets Y The list of related assets for this entry. v1
author Object Y The author of this entry. v1
author.displayName value string mt_author.nickame Y The display name of this entry creator. v1
author.id value number mt_entry.entry_author_id Y Y The ID of this entry creator. v1
author.userpicUrl value string Y The URL of this entry creator’s userpic. The userpic will be made by UserpicThumbnailSize and UserpicAllowRect settings. If user does not set own userpic, will be returned empty string. v1
basename value string mt_entry.entry_basename The basename for this entry. v1
blog Object Y The blog of this entry. v1
blog.id value number mt_entry.entry_blog_id Y The ID of the blog that contains this entry. v1
body value string mt_entry.entry_text The contents of this entry that the text format is applied. [update in v2] if you want to get the raw contents, you should sent a “no_text_filter=1” parameter with authenticated request. v1
categories ARRAY Categories A list of categories associated with the entry. The first element of the array is the primary category. OTHER categories are sorted by label category. [Update in v2] The value of this property was changed from “category label” to “Categories object”. v1
class value string mt_entry.entry_class Y The object class for this entry. v1
commentCount value number mt_entry.entry_comment_count Y The number of comments for this entry. v1
comments ARRAY Comments Y The list of comments for this entry. The list is sorted by ID of the comment and The parent ID of the comment. v1
createdDate value iso 8601 datetime mt_entry.entry_created_on Y The created time for this entry. v1
customFields ARRAY Object The list of customfields data for this entry. v1
customField.basename value string mt_field.field_basename Y The basename of this customfield. v1
customField.value value string The value of this customfield. v1
date value iso 8601 datetime mt_entry.entry_authored_on The published time for this entry. v1
excerpt value string mt_entry.entry_excerpt The excerpt value of this entry if one is specified or, if not, an auto-generated excerpt from the Entry Body field followed by an ellipsis (“…”). If an excerpt is auto-generated also note that any HTML is stripped. The length of the auto-generated output of this tag can be set in the blog’s Entry Settings. v1
format value string mt_entry.entry_convert_breaks Y The text format of this entry. v2
id value number mt_entry.entry_id Y The ID of this entry. v1
keywords value string mt_entry.entry_keywords The keywords text for this entry. v1
modifiedDate value iso 8601 datetime mt_entry.entry_modified_on Y The last modified time for this entry. v1
more value string mt_entry.entry_text_more The extended contents for this entry. [update in v2] if you want to get the raw contents, you should sent a “no_text_filter=1” parameter with authenticated request. v1
permalink value value string Y The parmalink URL for this entry. v1
pingsSentUrl ARRAY string Y The list of TrackBack pings sent from this entry. v1
status value string
Draft
This entry is saved as draft.
entry_status is 1.
Publish
This entry is published.
entry_status is 2.
Review
This entry is waiting for approval.
entry_status is 3.
Future
This entry is scheduled for future publishing.
entry_status is 4.
Spam
This entry is marked as Spam.
entry_status is 5.
 v1
tags ARRAY string The list of entry tags for this entry. v1
title value string mt_entry.entry_title The title of this entry. v1
trackbackCount value number mt_entry.entry_comment_count The number of received trackbacks for this entry. v1
trackbacks ARRAY Trackbacks Y The list of received trackbacks for this entry. The list is sorted by the ID of trackback. v1
unpublishedDate value iso 8601 datetime mt_entry.entry_unpublished_on The unpublished time for this entry. v2
updatable value boolean Y
true
The user who accessed can update this entry.
false
The user who accessed cannot update this entry.
 v1

{ “excerpt” : “We are excited to announce that Six Apar…”, “status” : “Publish”, “date” : “2014-11-14T13:08:42¥u002b09:00”, “updatable” : false, “author” : { “userpicUrl” : null, “displayName” : “Yuji Takayama” }, “allowComments” : true, “comments” : [], “permalink” : "http://localhost/blog/20141114-1/2014/11/six-apart-acquires-topics-server-to-simplify-site-upgrades.html", “body” : “¥u003cp¥u003e¥u003cspan¥u003eWe are excited to announce that Six Apart has acquired Topics, a dynamic online publishing product. This offering will provide Six Apart customers with an easy and cost-effective way to adapt existing content to evolving digital platforms.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eThis new product will save Six Apart customers a significant amount of time and money by allowing users to upgrade their websites and applications without migrating from their current content management systems. Clients who need to scale large amounts of data or even revamp a website on an entirely new platform can now achieve these changes with minimal effort.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eSix Apart customers will benefit not only from saved time and money, but also from ease of use. Topics does not have a user interface, so there is no new software to learn. Instead, it exists as a middle layer between the data library and the published page - automatically gathering, organizing and redistributing data.¥u003c/span¥u003e¥u003c/p¥u003e”, “keywords” : “”, “allowTrackbacks” : false, “id” : 5, “trackbacks” : [], “modifiedDate” : “2014-11-14T13:17:52¥u002b09:00”, “trackbackCount” : “0”, “categories” : [], “blog” : { “id” : “1” }, “commentCount” : “0”, “tags” : [], “basename” : “six_apart_acquires_topics_server_to_simplify_site_upgrades”, “assets” : [], “pingsSentUrl” : [], “title” : “Six Apart Acquires Topics Server to Simplify Site Upgrades”, “class” : “entry”, “createdDate” : “2014-11-14T13:17:52¥u002b09:00”, “unpublishedDate” : “2014-11-14T13:17:52¥u002b09:00”, “more” : “”, “customFields” : [ { “basename” : “place”, “value” : “New York City” }, { “basename” : “agenda”, “value” : “Movable Type¥nTopics” } ] }

Entries

Retrieve a list of entries in the specified site.
GET/sites/{site_id}/entries{?search,searchFields,limit,offset,sortBy,sortOrder,fields,includeIds,excludeIds,status,maxComments,maxTrackbacks,no_text_filter,dateField,dateFrom,dateTo}

Authentication required if want to include unpublished entries.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to retrieve the list of entries.
404 Not Found Site not found.

Permissions

  • edit_entry
    • for retrieve unpublished entry

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/entries?search=&searchFields=&limit=&offset=&sortBy=&sortOrder=&fields=&includeIds=&excludeIds=&status=&maxComments=&maxTrackbacks=&no_text_filter=&dateField=&dateFrom=&dateTo=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

search
string (optional) 

Search query.

searchFields
string (optional) Default: title,body,more,keywords,excerpt,basename 

The comma separated field name list to search.

limit
number (optional) Default: 10 

Maximum number of entries to retrieve.

offset
number (optional) Default: 0 

0-indexed offset.

sortBy
string (optional) Default: authored_on 

The field name for sort. You can specify one of following values

  • authored_on
  • title
  • created_on
  • modified_on

sortOrder
string (optional) Default: descend 
descend
(default) Return entries in descending order.
ascend
Return entries in ascending order.
fields
string (optional) 

The field list to retrieve as part of the Entries resource. That list should be separated by comma. If this parameter is not specified, All fields will be returned.

includeIds
string (optional) 

The comma separated ID list of entries to include to result.

excludeIds
string (optional) 

The comma separated ID list of entries to exclude from result.

status
string (optional) 

Filter by container entry’s status.

Draft
entry_status is 1.
Publish
entry_status is 2.
Review
entry_status is 3.
Future
entry_status is 4.
Spam
entry_status is 5.

maxComments
number (optional) 

This is an optional parameter. Maximum number of comments to retrieve as part of the Entries resource. If this parameter is not supplied, no comments will be returned.

maxTrackbacks
number (optional) 

This is an optional parameter. Maximum number of received trackbacks to retrieve as part of the Entries resource. If this parameter is not supplied, no trackbacks will be returned.

no_text_filter
number (optional) Default: 0 

If you want to fetch the raw text, set to ‘1’. New in v2

dateField
string (optional) Default: created_on 

Specifies the field name to be used as a date field for filtering. (new in v3)

dateFrom
string (optional) 

The start date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

dateTo
string (optional) 

The end date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults": 1,
  "items": [
    {
      "excerpt": "We are excited to announce that Six Apar...",
      "status": "Publish",
      "date": "2014-11-14T13:08:42¥u002b09:00",
      "updatable": false,
      "author": {
        "userpicUrl": null,
        "displayName": "Yuji Takayama"
      },
      "allowComments": true,
      "comments": [],
      "permalink": "http://localhost/blog/20141114-1/2014/11/six-apart-acquires-topics-server-to-simplify-site-upgrades.html",
      "body": "¥u003cp¥u003e¥u003cspan¥u003eWe are excited to announce that Six Apart has acquired Topics, a dynamic online publishing product. This offering will provide Six Apart customers with an easy and cost-effective way to adapt existing content to evolving digital platforms.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eThis new product will save Six Apart customers a significant amount of time and money by allowing users to upgrade their websites and applications without migrating from their current content management systems. Clients who need to scale large amounts of data or even revamp a website on an entirely new platform can now achieve these changes with minimal effort.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eSix Apart customers will benefit not only from saved time and money, but also from ease of use. Topics does not have a user interface, so there is no new software to learn. Instead, it exists as a middle layer between the data library and the published page - automatically gathering, organizing and redistributing data.¥u003c/span¥u003e¥u003c/p¥u003e",
      "keywords": "",
      "allowTrackbacks": false,
      "id": 5,
      "trackbacks": [],
      "modifiedDate": "2014-11-14T13:17:52¥u002b09:00",
      "trackbackCount": "0",
      "categories": [],
      "blog": {
        "id": "1"
      },
      "commentCount": "0",
      "tags": [],
      "basename": "six_apart_acquires_topics_server_to_simplify_site_upgrades",
      "assets": [],
      "pingsSentUrl": [],
      "title": "Six Apart Acquires Topics Server to Simplify Site Upgrades",
      "class": "entry",
      "createdDate": "2014-11-14T13:17:52¥u002b09:00",
      "more": "",
      "customFields": [
        {
          "basename": "place",
          "value": "New York City"
        },
        {
          "basename": "agenda",
          "value": "Movable Type¥nTopics"
        }
      ]
    }
  ]
}

Retrieve a list of entries by category.
GET/sites/{site_id}/categories/{category_id}/entries{?search,searchFields,limit,offset,sortBy,sortOrder,fields,includeIds,excludeIds,status,maxComments,maxTrackbacks,no_text_filter,dateField,dateFrom,dateTo}

Authentication required. if want to include unpublished entries.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to retrieve the list of entries.
404 Not Found Site or Category not found.

Permissions

  • edit_entry
    • for retrieve unpublished entry

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/categories/category_id/entries?search=&searchFields=&limit=&offset=&sortBy=&sortOrder=&fields=&includeIds=&excludeIds=&status=&maxComments=&maxTrackbacks=&no_text_filter=&dateField=&dateFrom=&dateTo=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

category_id
number (required) 

The category ID.

search
string (optional) 

Search query.

searchFields
string (optional) Default: title,body,more,keywords,excerpt,basename 

The comma separated field name list to search.

limit
number (optional) Default: 10 

Maximum number of entries to retrieve.

offset
number (optional) Default: 0 

0-indexed offset.

sortBy
string (optional) Default: authored_on 

The field name for sort. You can specify one of following values

  • authored_on
  • title
  • created_on
  • modified_on

sortOrder
string (optional) Default: descend 
descend
(default) Return entries in descending order.
ascend
Return entries in ascending order.
fields
string (optional) 

The field list to retrieve as part of the Entries resource. That list should be separated by comma. If this parameter is not specified, All fields will be returned.

includeIds
string (optional) 

The comma separated ID list of entries to include to result.

excludeIds
string (optional) 

The comma separated ID list of entries to exclude from result.

status
string (optional) 

Filter by container entry’s status.

Draft
entry_status is 1.
Publish
entry_status is 2.
Review
entry_status is 3.
Future
entry_status is 4.
Spam
entry_status is 5.

maxComments
number (optional) 

This is an optional parameter. Maximum number of comments to retrieve as part of the Entries resource. If this parameter is not supplied, no comments will be returned.

maxTrackbacks
number (optional) 

This is an optional parameter. Maximum number of received trackbacks to retrieve as part of the Entries resource. If this parameter is not supplied, no trackbacks will be returned.

no_text_filter
number (optional) Default: 0 

If you want to fetch the raw text, set to ‘1’. New in v2

dateField
string (optional) Default: created_on 

Specifies the field name to be used as a date field for filtering. (new in v3)

dateFrom
string (optional) 

The start date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

dateTo
string (optional) 

The end date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults": 1,
  "items": [
    {
      "excerpt": "We are excited to announce that Six Apar...",
      "status": "Publish",
      "date": "2014-11-14T13:08:42¥u002b09:00",
      "updatable": false,
      "author": {
        "userpicUrl": null,
        "displayName": "Yuji Takayama"
      },
      "allowComments": true,
      "comments": [],
      "permalink": "http://localhost/blog/20141114-1/2014/11/six-apart-acquires-topics-server-to-simplify-site-upgrades.html",
      "body": "¥u003cp¥u003e¥u003cspan¥u003eWe are excited to announce that Six Apart has acquired Topics, a dynamic online publishing product. This offering will provide Six Apart customers with an easy and cost-effective way to adapt existing content to evolving digital platforms.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eThis new product will save Six Apart customers a significant amount of time and money by allowing users to upgrade their websites and applications without migrating from their current content management systems. Clients who need to scale large amounts of data or even revamp a website on an entirely new platform can now achieve these changes with minimal effort.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eSix Apart customers will benefit not only from saved time and money, but also from ease of use. Topics does not have a user interface, so there is no new software to learn. Instead, it exists as a middle layer between the data library and the published page - automatically gathering, organizing and redistributing data.¥u003c/span¥u003e¥u003c/p¥u003e",
      "keywords": "",
      "allowTrackbacks": false,
      "id": 5,
      "trackbacks": [],
      "modifiedDate": "2014-11-14T13:17:52¥u002b09:00",
      "trackbackCount": "0",
      "categories": [],
      "blog": {
        "id": "1"
      },
      "commentCount": "0",
      "tags": [],
      "basename": "six_apart_acquires_topics_server_to_simplify_site_upgrades",
      "assets": [],
      "pingsSentUrl": [],
      "title": "Six Apart Acquires Topics Server to Simplify Site Upgrades",
      "class": "entry",
      "createdDate": "2014-11-14T13:17:52¥u002b09:00",
      "more": "",
      "customFields": [
        {
          "basename": "place",
          "value": "New York City"
        },
        {
          "basename": "agenda",
          "value": "Movable Type¥nTopics"
        }
      ]
    }
  ]
}

Retrieve a list of entries that related with asset.
GET/sites/{site_id}/assets/{asset_id}/entries{?search,searchFields,limit,offset,sortBy,sortOrder,fields,includeIds,excludeIds,status,maxComments,maxTrackbacks,no_text_filter,dateField,dateFrom,dateTo}

Authentication required. if want to include unpublished entries.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to retrieve the list of entries.
404 Not Found Site or Asset not found.

Permissions

  • edit_entry
    • for retrieve unpublished entry

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/assets/asset_id/entries?search=&searchFields=&limit=&offset=&sortBy=&sortOrder=&fields=&includeIds=&excludeIds=&status=&maxComments=&maxTrackbacks=&no_text_filter=&dateField=&dateFrom=&dateTo=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

asset_id
number (required) 

The asset ID.

search
string (optional) 

Search query.

searchFields
string (optional) Default: title,body,more,keywords,excerpt,basename 

The comma separated field name list to search.

limit
number (optional) Default: 10 

Maximum number of entries to retrieve.

offset
number (optional) Default: 0 

0-indexed offset.

sortBy
string (optional) Default: authored_on 

The field name for sort. You can specify one of following values

  • authored_on
  • title
  • created_on
  • modified_on

sortOrder
string (optional) Default: descend 
descend
(default) Return entries in descending order.
ascend
Return entries in ascending order.
fields
string (optional) 

The field list to retrieve as part of the Entries resource. That list should be separated by comma. If this parameter is not specified, All fields will be returned.

includeIds
string (optional) 

The comma separated ID list of entries to include to result.

excludeIds
string (optional) 

The comma separated ID list of entries to exclude from result.

status
string (optional) 

Filter by container entry’s status.

Draft
entry_status is 1.
Publish
entry_status is 2.
Review
entry_status is 3.
Future
entry_status is 4.
Spam
entry_status is 5.

maxComments
number (optional) 

This is an optional parameter. Maximum number of comments to retrieve as part of the Entries resource. If this parameter is not supplied, no comments will be returned.

maxTrackbacks
number (optional) 

This is an optional parameter. Maximum number of received trackbacks to retrieve as part of the Entries resource. If this parameter is not supplied, no trackbacks will be returned.

no_text_filter
number (optional) Default: 0 

If you want to fetch the raw text, set to ‘1’. New in v2

dateField
string (optional) Default: created_on 

Specifies the field name to be used as a date field for filtering. (new in v3)

dateFrom
string (optional) 

The start date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

dateTo
string (optional) 

The end date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults": 1,
  "items": [
    {
      "excerpt": "We are excited to announce that Six Apar...",
      "status": "Publish",
      "date": "2014-11-14T13:08:42¥u002b09:00",
      "updatable": false,
      "author": {
        "userpicUrl": null,
        "displayName": "Yuji Takayama"
      },
      "allowComments": true,
      "comments": [],
      "permalink": "http://localhost/blog/20141114-1/2014/11/six-apart-acquires-topics-server-to-simplify-site-upgrades.html",
      "body": "¥u003cp¥u003e¥u003cspan¥u003eWe are excited to announce that Six Apart has acquired Topics, a dynamic online publishing product. This offering will provide Six Apart customers with an easy and cost-effective way to adapt existing content to evolving digital platforms.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eThis new product will save Six Apart customers a significant amount of time and money by allowing users to upgrade their websites and applications without migrating from their current content management systems. Clients who need to scale large amounts of data or even revamp a website on an entirely new platform can now achieve these changes with minimal effort.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eSix Apart customers will benefit not only from saved time and money, but also from ease of use. Topics does not have a user interface, so there is no new software to learn. Instead, it exists as a middle layer between the data library and the published page - automatically gathering, organizing and redistributing data.¥u003c/span¥u003e¥u003c/p¥u003e",
      "keywords": "",
      "allowTrackbacks": false,
      "id": 5,
      "trackbacks": [],
      "modifiedDate": "2014-11-14T13:17:52¥u002b09:00",
      "trackbackCount": "0",
      "categories": [],
      "blog": {
        "id": "1"
      },
      "commentCount": "0",
      "tags": [],
      "basename": "six_apart_acquires_topics_server_to_simplify_site_upgrades",
      "assets": [],
      "pingsSentUrl": [],
      "title": "Six Apart Acquires Topics Server to Simplify Site Upgrades",
      "class": "entry",
      "createdDate": "2014-11-14T13:17:52¥u002b09:00",
      "more": "",
      "customFields": [
        {
          "basename": "place",
          "value": "New York City"
        },
        {
          "basename": "agenda",
          "value": "Movable Type¥nTopics"
        }
      ]
    }
  ]
}

Retrieve a list of entries that related with tag.
GET/sites/{site_id}/tags/{tag_id}/entries{?search,searchFields,limit,offset,sortBy,sortOrder,fields,includeIds,excludeIds,status,status,maxComments,maxTrackbacks,no_text_filter,dateField,dateFrom,dateTo}

  • Authentication required. if want to include unpublished entries.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to retrieve the list of entries.
404 Not Found Site or Tag not found.

Permissions

  • edit_entry
    • for retrieve unpublished entry

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/tags/tag_id/entries?search=&searchFields=&limit=&offset=&sortBy=&sortOrder=&fields=&includeIds=&excludeIds=&status=&status=&maxComments=&maxTrackbacks=&no_text_filter=&dateField=&dateFrom=&dateTo=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

tag_id
number (required) 

The tag ID.

search
string (optional) 

Search query.

searchFields
string (optional) Default: title,body,more,keywords,excerpt,basename 

The comma separated field name list to search.

limit
number (optional) Default: 10 

Maximum number of entries to retrieve.

offset
number (optional) Default: 0 

0-indexed offset.

sortBy
string (optional) Default: authored_on 

The field name for sort. You can specify one of following values

  • authored_on
  • title
  • created_on
  • modified_on

sortOrder
string (optional) Default: descend 
descend
(default) Return entries in descending order.
ascend
Return entries in ascending order.
fields
string (optional) 

The field list to retrieve as part of the Entries resource. That list should be separated by comma. If this parameter is not specified, All fields will be returned.

includeIds
string (optional) 

The comma separated ID list of entries to include to result.

excludeIds
string (optional) 

The comma separated ID list of entries to exclude from result.

status
string (optional) 

Filter by container entry’s status.

Draft
entry_status is 1.
Publish
entry_status is 2.
Review
entry_status is 3.
Future
entry_status is 4.
Spam
entry_status is 5.

maxComments
number (optional) 

This is an optional parameter. Maximum number of comments to retrieve as part of the Entries resource. If this parameter is not supplied, no comments will be returned.

maxTrackbacks
number (optional) 

This is an optional parameter. Maximum number of received trackbacks to retrieve as part of the Entries resource. If this parameter is not supplied, no trackbacks will be returned.

no_text_filter
number (optional) Default: 0 

If you want to fetch the raw text, set to ‘1’. New in v2

dateField
string (optional) Default: created_on 

Specifies the field name to be used as a date field for filtering. (new in v3)

dateFrom
string (optional) 

The start date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

dateTo
string (optional) 

The end date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults": 1,
  "items": [
    {
      "excerpt": "We are excited to announce that Six Apar...",
      "status": "Publish",
      "date": "2014-11-14T13:08:42¥u002b09:00",
      "updatable": false,
      "author": {
        "userpicUrl": null,
        "displayName": "Yuji Takayama"
      },
      "allowComments": true,
      "comments": [],
      "permalink": "http://localhost/blog/20141114-1/2014/11/six-apart-acquires-topics-server-to-simplify-site-upgrades.html",
      "body": "¥u003cp¥u003e¥u003cspan¥u003eWe are excited to announce that Six Apart has acquired Topics, a dynamic online publishing product. This offering will provide Six Apart customers with an easy and cost-effective way to adapt existing content to evolving digital platforms.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eThis new product will save Six Apart customers a significant amount of time and money by allowing users to upgrade their websites and applications without migrating from their current content management systems. Clients who need to scale large amounts of data or even revamp a website on an entirely new platform can now achieve these changes with minimal effort.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eSix Apart customers will benefit not only from saved time and money, but also from ease of use. Topics does not have a user interface, so there is no new software to learn. Instead, it exists as a middle layer between the data library and the published page - automatically gathering, organizing and redistributing data.¥u003c/span¥u003e¥u003c/p¥u003e",
      "keywords": "",
      "allowTrackbacks": false,
      "id": 5,
      "trackbacks": [],
      "modifiedDate": "2014-11-14T13:17:52¥u002b09:00",
      "trackbackCount": "0",
      "categories": [],
      "blog": {
        "id": "1"
      },
      "commentCount": "0",
      "tags": [],
      "basename": "six_apart_acquires_topics_server_to_simplify_site_upgrades",
      "assets": [],
      "pingsSentUrl": [],
      "title": "Six Apart Acquires Topics Server to Simplify Site Upgrades",
      "class": "entry",
      "createdDate": "2014-11-14T13:17:52¥u002b09:00",
      "more": "",
      "customFields": [
        {
          "basename": "place",
          "value": "New York City"
        },
        {
          "basename": "agenda",
          "value": "Movable Type¥nTopics"
        }
      ]
    }
  ]
}

Create a new entry.
POST/sites/{site_id}/entries

  • Authentication required.

Update in v2.0

  • You can attach categories and assets in the one request.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to create a new entry.
404 Not Found Site not found.

Permissions

  • create_post

Request Body Parameters

Name Type Required Default Description
entry Object Yes Single Entries resource

Example URI

POST http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/entries
URI Parameters
HideShow
site_id
number (required) 

The site ID.

Request  Entries resource
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Body
entry={"excerpt" : "We are excited to announce that Six Apar...","status" : "Publish","allowComments" : true,"body" : "¥u003cp¥u003e¥u003cspan¥u003eWe are excited to announce that Six Apart has acquired Topics, a dynamic online publishing product. This offering will provide Six Apart customers with an easy and cost-effective way to adapt existing content to evolving digital platforms.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eThis new product will save Six Apart customers a significant amount of time and money by allowing users to upgrade their websites and applications without migrating from their current content management systems. Clients who need to scale large amounts of data or even revamp a website on an entirely new platform can now achieve these changes with minimal effort.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eSix Apart customers will benefit not only from saved time and money, but also from ease of use. Topics does not have a user interface, so there is no new software to learn. Instead, it exists as a middle layer between the data library and the published page - automatically gathering, organizing and redistributing data.¥u003c/span¥u003e¥u003c/p¥u003e","keywords" : "","allowTrackbacks" : false,"basename" : "six_apart_acquires_topics_server_to_simplify_site_upgrades","title" : "Six Apart Acquires Topics Server to Simplify Site Upgrades","more" : "","customFields" : [{"basename" : "place","value" : "New York City"},{"basename" : "agenda","value" : "Movable Type¥nTopics"}]}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "excerpt": "We are excited to announce that Six Apar...",
  "status": "Publish",
  "date": "2014-11-14T13:08:42¥u002b09:00",
  "updatable": false,
  "author": {
    "userpicUrl": null,
    "displayName": "Yuji Takayama"
  },
  "allowComments": true,
  "comments": [],
  "permalink": "http://localhost/blog/20141114-1/2014/11/six-apart-acquires-topics-server-to-simplify-site-upgrades.html",
  "body": "¥u003cp¥u003e¥u003cspan¥u003eWe are excited to announce that Six Apart has acquired Topics, a dynamic online publishing product. This offering will provide Six Apart customers with an easy and cost-effective way to adapt existing content to evolving digital platforms.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eThis new product will save Six Apart customers a significant amount of time and money by allowing users to upgrade their websites and applications without migrating from their current content management systems. Clients who need to scale large amounts of data or even revamp a website on an entirely new platform can now achieve these changes with minimal effort.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eSix Apart customers will benefit not only from saved time and money, but also from ease of use. Topics does not have a user interface, so there is no new software to learn. Instead, it exists as a middle layer between the data library and the published page - automatically gathering, organizing and redistributing data.¥u003c/span¥u003e¥u003c/p¥u003e",
  "keywords": "",
  "allowTrackbacks": false,
  "id": 5,
  "trackbacks": [],
  "modifiedDate": "2014-11-14T13:17:52¥u002b09:00",
  "trackbackCount": "0",
  "categories": [],
  "blog": {
    "id": "1"
  },
  "commentCount": "0",
  "tags": [],
  "basename": "six_apart_acquires_topics_server_to_simplify_site_upgrades",
  "assets": [],
  "pingsSentUrl": [],
  "title": "Six Apart Acquires Topics Server to Simplify Site Upgrades",
  "class": "entry",
  "createdDate": "2014-11-14T13:17:52¥u002b09:00",
  "more": "",
  "customFields": [
    {
      "basename": "place",
      "value": "New York City"
    },
    {
      "basename": "agenda",
      "value": "Movable Type¥nTopics"
    }
  ]
}

Retrieve a single entry by its ID.
GET/sites/{site_id}/entries/{entry_id}{?fields}

Authentication required if the entry status is “unpublished”.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to retrieve the requested entry.
404 Not Found Site or Entry not found.

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/entries/entry_id?fields=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

entry_id
number (required) 

The entry ID.

fields
string (optional) 

The field list to retrieve as part of the Entries resource. That list should be separated by comma. If this parameter is not specified, All fields will be returned.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "excerpt": "We are excited to announce that Six Apar...",
  "status": "Publish",
  "date": "2014-11-14T13:08:42¥u002b09:00",
  "updatable": false,
  "author": {
    "userpicUrl": null,
    "displayName": "Yuji Takayama"
  },
  "allowComments": true,
  "comments": [],
  "permalink": "http://localhost/blog/20141114-1/2014/11/six-apart-acquires-topics-server-to-simplify-site-upgrades.html",
  "body": "¥u003cp¥u003e¥u003cspan¥u003eWe are excited to announce that Six Apart has acquired Topics, a dynamic online publishing product. This offering will provide Six Apart customers with an easy and cost-effective way to adapt existing content to evolving digital platforms.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eThis new product will save Six Apart customers a significant amount of time and money by allowing users to upgrade their websites and applications without migrating from their current content management systems. Clients who need to scale large amounts of data or even revamp a website on an entirely new platform can now achieve these changes with minimal effort.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eSix Apart customers will benefit not only from saved time and money, but also from ease of use. Topics does not have a user interface, so there is no new software to learn. Instead, it exists as a middle layer between the data library and the published page - automatically gathering, organizing and redistributing data.¥u003c/span¥u003e¥u003c/p¥u003e",
  "keywords": "",
  "allowTrackbacks": false,
  "id": 5,
  "trackbacks": [],
  "modifiedDate": "2014-11-14T13:17:52¥u002b09:00",
  "trackbackCount": "0",
  "categories": [],
  "blog": {
    "id": "1"
  },
  "commentCount": "0",
  "tags": [],
  "basename": "six_apart_acquires_topics_server_to_simplify_site_upgrades",
  "assets": [],
  "pingsSentUrl": [],
  "title": "Six Apart Acquires Topics Server to Simplify Site Upgrades",
  "class": "entry",
  "createdDate": "2014-11-14T13:17:52¥u002b09:00",
  "more": "",
  "customFields": [
    {
      "basename": "place",
      "value": "New York City"
    },
    {
      "basename": "agenda",
      "value": "Movable Type¥nTopics"
    }
  ]
}

Update an existing entry.
PUT/sites/{site_id}/entries/{entry_id}

Authentication required.

This method accepts PUT and POST with __method=PUT.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to update the speciied entry.
404 Not Found Site or Entry not found.

Permissions

  • edit_entry
    • for retrieve unpublished entry

Example URI

PUT http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/entries/entry_id
URI Parameters
HideShow
site_id
number (required) 

The site ID.

entry_id
number (required) 

The entry ID.

Request  Entries resource
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Body
entry={"excerpt" : "We are excited to announce that Six Apar...","status" : "Publish","allowComments" : true,"body" : "¥u003cp¥u003e¥u003cspan¥u003eWe are excited to announce that Six Apart has acquired Topics, a dynamic online publishing product. This offering will provide Six Apart customers with an easy and cost-effective way to adapt existing content to evolving digital platforms.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eThis new product will save Six Apart customers a significant amount of time and money by allowing users to upgrade their websites and applications without migrating from their current content management systems. Clients who need to scale large amounts of data or even revamp a website on an entirely new platform can now achieve these changes with minimal effort.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eSix Apart customers will benefit not only from saved time and money, but also from ease of use. Topics does not have a user interface, so there is no new software to learn. Instead, it exists as a middle layer between the data library and the published page - automatically gathering, organizing and redistributing data.¥u003c/span¥u003e¥u003c/p¥u003e","keywords" : "","allowTrackbacks" : false,"basename" : "six_apart_acquires_topics_server_to_simplify_site_upgrades","title" : "Six Apart Acquires Topics Server to Simplify Site Upgrades","more" : "","customFields" : [{"basename" : "place","value" : "New York City"},{"basename" : "agenda","value" : "Movable Type¥nTopics"}]}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "excerpt": "We are excited to announce that Six Apar...",
  "status": "Publish",
  "date": "2014-11-14T13:08:42¥u002b09:00",
  "updatable": false,
  "author": {
    "userpicUrl": null,
    "displayName": "Yuji Takayama"
  },
  "allowComments": true,
  "comments": [],
  "permalink": "http://localhost/blog/20141114-1/2014/11/six-apart-acquires-topics-server-to-simplify-site-upgrades.html",
  "body": "¥u003cp¥u003e¥u003cspan¥u003eWe are excited to announce that Six Apart has acquired Topics, a dynamic online publishing product. This offering will provide Six Apart customers with an easy and cost-effective way to adapt existing content to evolving digital platforms.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eThis new product will save Six Apart customers a significant amount of time and money by allowing users to upgrade their websites and applications without migrating from their current content management systems. Clients who need to scale large amounts of data or even revamp a website on an entirely new platform can now achieve these changes with minimal effort.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eSix Apart customers will benefit not only from saved time and money, but also from ease of use. Topics does not have a user interface, so there is no new software to learn. Instead, it exists as a middle layer between the data library and the published page - automatically gathering, organizing and redistributing data.¥u003c/span¥u003e¥u003c/p¥u003e",
  "keywords": "",
  "allowTrackbacks": false,
  "id": 5,
  "trackbacks": [],
  "modifiedDate": "2014-11-14T13:17:52¥u002b09:00",
  "trackbackCount": "0",
  "categories": [],
  "blog": {
    "id": "1"
  },
  "commentCount": "0",
  "tags": [],
  "basename": "six_apart_acquires_topics_server_to_simplify_site_upgrades",
  "assets": [],
  "pingsSentUrl": [],
  "title": "Six Apart Acquires Topics Server to Simplify Site Upgrades",
  "class": "entry",
  "createdDate": "2014-11-14T13:17:52¥u002b09:00",
  "more": "",
  "customFields": [
    {
      "basename": "place",
      "value": "New York City"
    },
    {
      "basename": "agenda",
      "value": "Movable Type¥nTopics"
    }
  ]
}

Delete an existing entry.
DELETE/sites/{site_id}/entries/{entry_id}

Authentication required.

This method accepts PUT and POST with __method=DELETE.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to delete the speciied entry.
404 Not Found Site or Entry not found.

Permissions

  • edit_entry
    • for retrieve unpublished entry

Example URI

DELETE http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/entries/entry_id
URI Parameters
HideShow
site_id
number (required) 

The site ID.

entry_id
number (required) 

The entry ID.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "excerpt": "We are excited to announce that Six Apar...",
  "status": "Publish",
  "date": "2014-11-14T13:08:42¥u002b09:00",
  "updatable": false,
  "author": {
    "userpicUrl": null,
    "displayName": "Yuji Takayama"
  },
  "allowComments": true,
  "comments": [],
  "permalink": "http://localhost/blog/20141114-1/2014/11/six-apart-acquires-topics-server-to-simplify-site-upgrades.html",
  "body": "¥u003cp¥u003e¥u003cspan¥u003eWe are excited to announce that Six Apart has acquired Topics, a dynamic online publishing product. This offering will provide Six Apart customers with an easy and cost-effective way to adapt existing content to evolving digital platforms.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eThis new product will save Six Apart customers a significant amount of time and money by allowing users to upgrade their websites and applications without migrating from their current content management systems. Clients who need to scale large amounts of data or even revamp a website on an entirely new platform can now achieve these changes with minimal effort.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eSix Apart customers will benefit not only from saved time and money, but also from ease of use. Topics does not have a user interface, so there is no new software to learn. Instead, it exists as a middle layer between the data library and the published page - automatically gathering, organizing and redistributing data.¥u003c/span¥u003e¥u003c/p¥u003e",
  "keywords": "",
  "allowTrackbacks": false,
  "id": 5,
  "trackbacks": [],
  "modifiedDate": "2014-11-14T13:17:52¥u002b09:00",
  "trackbackCount": "0",
  "categories": [],
  "blog": {
    "id": "1"
  },
  "commentCount": "0",
  "tags": [],
  "basename": "six_apart_acquires_topics_server_to_simplify_site_upgrades",
  "assets": [],
  "pingsSentUrl": [],
  "title": "Six Apart Acquires Topics Server to Simplify Site Upgrades",
  "class": "entry",
  "createdDate": "2014-11-14T13:17:52¥u002b09:00",
  "more": "",
  "customFields": [
    {
      "basename": "place",
      "value": "New York City"
    },
    {
      "basename": "agenda",
      "value": "Movable Type¥nTopics"
    }
  ]
}

Preview

Make a preview by specified data.
POST/sites/{site_id}/entries/preview{?raw}

Authentication required.

This endpoint is available in Movable Type 6.1.2 or later.

Permissions

  • create_post

Example URI

POST http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/entries/preview?raw=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

raw
number (optional) 

If specify “1”, will be returned preview contents.

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Body
entry={ "title" : "My First Post", "body" : "This is my first post!" }
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": "success",
  "preview": "http://example.com/2015/07/my-first-post.html"
}
Response  403
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Do not have permission to get entry preview.",
    "code": "403"
  }
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Site not found",
    "code": "404"
  }
}
Response  500
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Some error message is here",
    "code": "500"
  }
}

Make a preview for existing data.
POST/sites/{site_id}/entries/{entry_id}/preview{?raw}

Authentication required.

This endpoint is available in Movable Type 6.1.2 or later.

entry parameter is required. If you just want to get preview entry from existing data, you should provide entry parameter with empty json. This will be fixed in the future.

Permissions

  • create_post

Example URI

POST http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/entries/entry_id/preview?raw=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

entry_id
number (required) 

The entry ID.

raw
number (optional) 

If specify “1”, will be returned preview contents.

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Body
entry={}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": "success",
  "preview": "http://example.com/2015/07/existing-entry.html"
}
Response  403
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Do not have permission to get entry preview.",
    "code": "403"
  }
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Site not found / Entry not found",
    "code": "404"
  }
}
Response  500
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Some error message is here",
    "code": "500"
  }
}

Folders

This is the Folders resource.

Property Name Type Data Type Database Column Private Read Only Description Version
basename value string mt_category.category_basename The basename for this folder. v2
blog Object Blog Y The blog for this folder. v2
blog.id value number mt_category.category_blog_id Y The ID of the blog that contains this folder. v2
class value string mt_category.category_class Y The class for this folder. Always “folder”. v2
createdBy Object User Y Created user of this folder. v2
createdBy.displayName value string mt_author.author_nickname Y The display name of this folder creator. v2
createdBy.id value number mt_category.category_created_by Y Y The ID of this folder creator. v2
createdBy.userpicUrl value string mt_author.author_userpic_url Y The URL of this folder creator’s userpic. The userpic will be made by UserpicThumbnailSize and UserpicAllowRect settings. If user does not set own userpic, will be returned empty string. v2
createdDate value iso 8601 datetime mt_category.category_created_on Y Created date of this folder. v2
customFields ARRAY Object Y The list of customfields data for this folder. v2
customField.basename value string mt_field.field_basename Y The basename for this customfield. v2
customField.value value string mt_template_meta.* The value of this customfield. v2
description value string mt_category.category_description The description for this folder. v2
id value number mt_category.category_id Y The ID for this folder. v2
label value string mt_category.category_label The label for this folder. v2
modifiedBy Object User Y Last modified user of this folder. v2
modifiedBy.displayName value string mt_author.author_nickname Y The display name of this folder modifier. v2
modifiedBy.id value number mt_category.category_modified_by Y Y The ID of this folder modifier. v2
modifiedBy.userpicUrl value string mt_author.author_userpic_url Y The URL of this folder modifier’s userpic. The userpic will be made by UserpicThumbnailSize and UserpicAllowRect settings. If user does not set own userpic, will be returned empty string. New in v2
modifiedDate value iso 8601 datetime mt_category.category_modified_on Y Last modified date of this folder. v2
path value string Y The path for this folder. v2
updatable value boolean Y
true
The user who accessed can update this folder.
false
The user who accessed cannot update this folder.
 v2

{ “parent”: “0”, “createdBy”: { “userpicUrl”: null, “displayName”: “Yuji Takayama” }, “updatable”: false, “blog”: { “id”: “2” }, “path”: "http://path/to/downloads/", “description”: null, “basename”: “downloads”, “label”: “downloads”, “class”: “folder”, “id”: 12, “createdDate”: “2015-03-30T22:47:08+09:00”, “modifiedDate”: “2015-03-30T22:47:08+09:00”, “customFields”: [] },

Folders

Retrieve a list of folders
GET/sites/{site_id}/folders{?limit,offset,sortBy,sortOrder,fields,searchFields,search,includeIds,excludeIds,top,dateField,dateFrom,dateTo}

Authentication required if you want to get private properties.

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/folders?limit=&offset=&sortBy=&sortOrder=&fields=&searchFields=&search=&includeIds=&excludeIds=&top=&dateField=&dateFrom=&dateTo=
URI Parameters
HideShow
site_id
number (required) 

The site ID

limit
number (optional) Default: 10 

Maximum number of folders to retrieve.

offset
number (optional) Default: 0 

0-indexed offset.

sortBy
string (optional) Default: user_custom 
user_custom
Sort order you specified on the Manage Folders screen.
created_by
Sort by the ID of creator.
id
Sort by its own ID.
basename
Sort by the basename of each folders.
label
Sort by the label of each folders.
sortOrder
string (optional) Default: descend 
descend
(default) Return folders in descending order.
ascend
Return folders in ascending order.
fields
string (optional) 

The field list to retrieve as part of the Folders resource. That list should be separated by comma. If this parameter is not specified, All fields will be returned.

searchFields
string (optional) Default: label,basename 

The comma separated field name list to search.

search
string (optional) 

Search query.

includeIds
string (optional) 

The comma separated ID list of folders to include to result.

excludeIds
string (optional) 

The comma separated ID list of folders to exclude from result.

top
number (optional) Default: 0 

If set to 1, retrieves only top level folders.

dateField
string (optional) Default: created_on 

Specifies the field name to be used as a date field for filtering. (new in v3)

dateFrom
string (optional) 

The start date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

dateTo
string (optional) 

The end date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults" : "1",
  "items" : [
    {
      "parent": "0",
      "createdBy": {
        "userpicUrl": null,
        "displayName": "Yuji Takayama"
      },
      "updatable": false,
      "blog": {
        "id": "2"
      },
      "path": "http://path/to/downloads/",
      "description": null,
      "basename": "downloads",
      "label": "downloads",
      "class": "folder",
      "id": 12,
      "createdDate": "2015-03-30T22:47:08+09:00",
      "modifiedDate": "2015-03-30T22:47:08+09:00",
      "customFields": []
    },
  ]
}

Retrieve a list of parent folders
GET/sites/{site_id}/folders/{folder_id}/parents{?maxDepth,includeCurrent,dateField,dateFrom,dateTo}

Authentication required if you want to get private properties.

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/folders/folder_id/parents?maxDepth=&includeCurrent=&dateField=&dateFrom=&dateTo=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

folder_id
number (required) 

The folder ID.

maxDepth
numner (optional) 

The depth of retrieving parent folders.

includeCurrent
number (optional) Default: 0 
1
The results includes current folder.
0
The results do not include current folder.
dateField
string (optional) Default: created_on 

Specifies the field name to be used as a date field for filtering. (new in v3)

dateFrom
string (optional) 

The start date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

dateTo
string (optional) 

The end date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults" : "1",
  "items" : [
    {
      "parent": "0",
      "createdBy": {
        "userpicUrl": null,
        "displayName": "Yuji Takayama"
      },
      "updatable": false,
      "blog": {
        "id": "2"
      },
      "path": "http://path/to/downloads/",
      "description": null,
      "basename": "downloads",
      "label": "downloads",
      "class": "folder",
      "id": 12,
      "createdDate": "2015-03-30T22:47:08+09:00",
      "modifiedDate": "2015-03-30T22:47:08+09:00",
      "customFields": []
    },
  ]
}

Retrieve a list of sibling folders
GET/sites/{site_id}/folders/{folder_id}/siblings{?limit,offset,sortBy,sortOrder,fields,searchFields,search,includeIds,excludeIds,top,dateField,dateFrom,dateTo}

Authentication required if you want to get private properties.

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/folders/folder_id/siblings?limit=&offset=&sortBy=&sortOrder=&fields=&searchFields=&search=&includeIds=&excludeIds=&top=&dateField=&dateFrom=&dateTo=
URI Parameters
HideShow
site_id
number (required) 

The site ID

folder_id
number (required) 

The folder ID.

limit
number (optional) Default: 10 

Maximum number of folders to retrieve.

offset
number (optional) Default: 0 

0-indexed offset.

sortBy
string (optional) Default: user_custom 
user_custom
Sort order you specified on the Manage Folders screen.
created_by
Sort by the ID of creator.
id
Sort by its own ID.
basename
Sort by the basename of each folders.
label
Sort by the label of each folders.
sortOrder
string (optional) Default: descend 
descend
(default) Return folders in descending order.
ascend
Return folders in ascending order.
fields
string (optional) 

The field list to retrieve as part of the Folders resource. That list should be separated by comma. If this parameter is not specified, All fields will be returned.

searchFields
string (optional) Default: label,basename 

The comma separated field name list to search.

search
string (optional) 

Search query.

includeIds
string (optional) 

The comma separated ID list of folders to include to result.

excludeIds
string (optional) 

The comma separated ID list of folders to exclude from result.

top
number (optional) Default: 0 

If set to 1, retrieves only top level folders.

dateField
string (optional) Default: created_on 

Specifies the field name to be used as a date field for filtering. (new in v3)

dateFrom
string (optional) 

The start date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

dateTo
string (optional) 

The end date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults" : "1",
  "items" : [
    {
      "parent": "0",
      "createdBy": {
        "userpicUrl": null,
        "displayName": "Yuji Takayama"
      },
      "updatable": false,
      "blog": {
        "id": "2"
      },
      "path": "http://path/to/downloads/",
      "description": null,
      "basename": "downloads",
      "label": "downloads",
      "class": "folder",
      "id": 12,
      "createdDate": "2015-03-30T22:47:08+09:00",
      "modifiedDate": "2015-03-30T22:47:08+09:00",
      "customFields": []
    },
  ]
}

Retrieve a list of child folders
GET/sites/{site_id}/folders/{folder_id}/children{?maxDepth,includeCurrent,dateField,dateFrom,dateTo}

  • Authentication required if you want to get private properties.

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/folders/folder_id/children?maxDepth=&includeCurrent=&dateField=&dateFrom=&dateTo=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

folder_id
number (required) 

The folder ID.

maxDepth
numner (optional) 

The depth of retrieving child folders.

includeCurrent
number (optional) Default: 0 
1
The results includes current folder.
0
The results do not include current folder.
dateField
string (optional) Default: created_on 

Specifies the field name to be used as a date field for filtering. (new in v3)

dateFrom
string (optional) 

The start date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

dateTo
string (optional) 

The end date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults" : "1",
  "items" : [
    {
      "parent": "0",
      "createdBy": {
        "userpicUrl": null,
        "displayName": "Yuji Takayama"
      },
      "updatable": false,
      "blog": {
        "id": "2"
      },
      "path": "http://path/to/downloads/",
      "description": null,
      "basename": "downloads",
      "label": "downloads",
      "class": "folder",
      "id": 12,
      "createdDate": "2015-03-30T22:47:08+09:00",
      "modifiedDate": "2015-03-30T22:47:08+09:00",
      "customFields": []
    },
  ]
}

Create a new folder.
POST/sites/{site_id}/folders

Authentication required.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to create a new folder.
404 Not Found Site not found.

Permission

  • Manage Pages

Request Body Parameters

Name Type Required Default Description
folder Object Yes Single Folders resource

Example URI

POST http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/folders
URI Parameters
HideShow
site_id
number (required) 

The site ID.

Request  Folders resource
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Body
folder={"basename" : "news","parent" : "0","label" : "News","description" : null}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "basename" : "news",
  "blog" : {
    "id" : "1"
  },
  "class" : "folder",
  "createdBy" : {
    "displayName" : "Masahiro IUCHI"
    "userpicUrl" : null,
  },
  "createdDate" : "2019-07-03T18:19:40+09:00",
  "customFields" : [],
  "description" : null,
  "id" : 2,
  "label" : "News",
  "modifiedDate" : "2019-07-03T18:19:40+09:00",
  "parent" : "0",
  "path" : "https://example.com/site/news",
  "updatable" : true
}

Retrieve a single folder by its ID.
GET/sites/{site_id}/folders/{folder_id}{?fields}

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to retrieve a folder.
404 Not Found Folder or site not found.

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/folders/folder_id?fields=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

folder_id
number (required) 

The folder ID.

fields
string (optional) 

The field list to retrieve as part of the Folders resource. The list of field names should be separated by commas. If this parameter is not specified, all fields will be returned.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "basename" : "news",
  "blog" : {
    "id" : "1"
  },
  "class" : "folder",
  "createdBy" : {
    "displayName" : "Masahiro IUCHI"
    "userpicUrl" : null,
  },
  "createdDate" : "2019-07-03T18:19:40+09:00",
  "customFields" : [],
  "description" : null,
  "id" : 2,
  "label" : "News",
  "modifiedDate" : "2019-07-03T18:19:40+09:00",
  "parent" : "0",
  "path" : "https://example.com/site/news",
  "updatable" : false,
}

Update an existing folder.
PUT/sites/{site_id}/folders/{folder_id}

Authentication required.

This method accepts PUT and POST with __method=PUT.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to update a folder.
404 Not Found Site or Folder not found.

Permission

  • Manage Pages

Request Body Parameters

Name Type Required Default Description
folder Object Yes Single Folders resource

Example URI

PUT http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/folders/folder_id
URI Parameters
HideShow
site_id
number (required) 

The site ID.

folder_id
number (required) 

The folder ID.

Request  Folders resource
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Body
folder={"basename" : "news","parent" : "0","label" : "News","description" : null}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "basename" : "news",
  "blog" : {
    "id" : "1"
  },
  "class" : "folder",
  "createdBy" : {
    "displayName" : "Masahiro IUCHI"
    "userpicUrl" : null,
  },
  "createdDate" : "2019-07-03T18:19:40+09:00",
  "customFields" : [],
  "description" : null,
  "id" : 2,
  "label" : "News",
  "modifiedDate" : "2019-07-03T18:19:40+09:00",
  "parent" : "0",
  "path" : "https://example.com/site/news",
  "updatable" : true,
}

Delete an existing fodler.
DELETE/sites/{site_id}/folders/{folder_id}

Authentication required.

This method accepts DELETE and POST with __method=DELETE.

This method returns deleted Folder resource.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to delete a folder.
404 Not Found Site or Folder not found.

Permission

  • Manage Pages

Example URI

DELETE http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/folders/folder_id
URI Parameters
HideShow
site_id
number (required) 

The site ID.

folder_id
number (required) 

The fodler ID.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "basename" : "news",
  "blog" : {
    "id" : "1"
  },
  "class" : "folder",
  "createdBy" : {
    "displayName" : "Masahiro IUCHI"
    "userpicUrl" : null,
  },
  "createdDate" : "2019-07-03T18:19:40+09:00",
  "customFields" : [],
  "description" : null,
  "id" : 2,
  "label" : "News",
  "modifiedDate" : "2019-07-03T18:19:40+09:00",
  "parent" : "0",
  "path" : "https://example.com/site/news",
  "updatable" : true,
}

Rearrange existing folders in a new order.
POST/sites/{site_id}/folders/permutate

Authentication required.

This method returns rearranged Folders resource.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to rearrange folders.
404 Not Found Site not found.

Permission

  • Manage Pages

Request Body Parameters

Name Type Required Default Description
folders ARRAY Yes Array of Folders resource that will be rearranged.

Example URI

POST http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/folders/permutate
URI Parameters
HideShow
site_id
number (required) 

The site ID.

Request  Assets resource
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Body
folders=[{"id" : "2"},{"id" : "2"}]
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  {
    "basename" : "news",
    "blog" : {
      "id" : "1"
    },
    "class" : "folder",
    "createdBy" : {
      "displayName" : "Masahiro IUCHI"
      "userpicUrl" : null,
    },
    "createdDate" : "2019-07-03T18:19:40+09:00",
    "customFields" : [],
    "description" : null,
    "id" : 2,
    "label" : "News",
    "modifiedDate" : "2019-07-03T18:19:40+09:00",
    "parent" : "0",
    "path" : "https://example.com/site/news",
    "updatable" : true,
  },
  {
    "basename" : "events",
    "blog" : {
      "id" : "1"
    },
    "class" : "folder",
    "createdBy" : {
      "displayName" : "Masahiro IUCHI"
      "userpicUrl" : null,
    },
    "createdDate" : "2019-07-03T18:19:40+09:00",
    "customFields" : [],
    "description" : null,
    "id" : 1,
    "label" : "Events",
    "modifiedDate" : "2019-07-03T18:19:40+09:00",
    "parent" : "0",
    "path" : "https://example.com/site/events",
    "updatable" : true,
  }
]

Pages

This is the Pages resource.

Property Name Type Data Type Database Column Private Read Only Description Version
allowComments value boolean mt_entry.entry_allow_comments
false
This page does not accepts comments. In the database, this value is 0.
true
This page accepts comments. In the database, this value is 1.
 v2
allowTrackbacks value boolean mt_entry.entry_allow_pings
false
This page does not accepts trackbacks. In the database, this value is 0.
true
This page accepts trackbacks. In the database, this value is 1.
 v2
assets ARRAY Assets Y The list of related assets for this page. v2
author Object Y The author of this page. v2
author.displayName value string mt_author.nickame Y The display name of this page creator. v2
author.id value number mt_entry.entry_author_id Y Y The ID of this page creator. v2
author.userpicUrl value string Y The URL of this page creator’s userpic. The userpic will be made by UserpicThumbnailSize and UserpicAllowRect settings. If user does not set own userpic, will be returned empty string. v2
basename value string mt_entry.entry_basename The basename for this page. v2
blog Object Y The blog of this page. v2
blog.id value number mt_entry.entry_blog_id Y The ID of the blog that contains this page. v2
body value string mt_entry.entry_text The contents of this page that the text format is applied. [update in v2] if you want to get the raw contents, you should sent a “no_text_filter=1” parameter with authenticated request. v2
folder Object Folder The container folder of this page. v2
class value string mt_entry.entry_class Y The object class for this page. v2
commentCount value number mt_entry.entry_comment_count Y The number of comments for this page. v2
comments ARRAY Comments Y The list of comments for this page. The list is sorted by ID of the comment and The parent ID of the comment. v2
createdDate value iso 8601 datetime mt_entry.entry_created_on Y The created time for this page. v2
customFields ARRAY Object The list of customfields data for this page. v2
customField.basename value string mt_field.field_basename Y The basename of this customfield. v2
customField.value value string The value of this customfield. v2
date value iso 8601 datetime mt_entry.entry_authored_on The published time for this page. v2
excerpt value string mt_entry.entry_excerpt The excerpt value of this page if one is specified or, if not, an auto-generated excerpt from the page Body field followed by an ellipsis (“…”). If an excerpt is auto-generated also note that any HTML is stripped. The length of the auto-generated output of this tag can be set in the blog’s page Settings. v2
format value string mt_entry.entry_convert_breaks Y The text format of this page. v2
id value number mt_entry.entry_id Y The ID of this page. v2
keywords value string mt_entry.entry_keywords The keywords text for this page. v2
modifiedDate value iso 8601 datetime mt_entry.entry_modified_on Y The last modified time for this page. v2
more value string mt_entry.entry_text_more The extended contents for this page. if you want to get the raw contents, you should sent a “no_text_filter=1” parameter with authenticated request. v2
permalink value value string Y The parmalink URL for this page. v2
pingsSentUrl ARRAY string Y The list of TrackBack pings sent from this page. v2
status value string
Draft
This page is saved as draft.
status is 1.
Publish
This page is published.
status is 2.
Review
This page is waiting for approval.
status is 3.
Future
This page is scheduled for future publishing.
status is 4.
Spam
This page is marked as Spam.
status is 5.
 v2
tags ARRAY string The list of page tags for this page. v2
title value string mt_entry.entry_title The title of this page. v2
trackbackCount value number mt_entry.entry_comment_count The number of received trackbacks for this page. v2
trackbacks ARRAY Trackbacks Y The list of received trackbacks for this page. The list is sorted by the ID of trackback. v2
updatable value boolean Y
true
The user who accessed can update this entry.
false
The user who accessed cannot update this page.
 v2

{ “excerpt” : “We are excited to announce that Six Apar…”, “status” : “Publish”, “date” : “2014-11-14T13:08:42¥u002b09:00”, “updatable” : false, “author” : { “userpicUrl” : null, “displayName” : “Yuji Takayama” }, “allowComments” : true, “comments” : [], “permalink” : "http://localhost/news/six-apart-acquires-topics-server-to-simplify-site-upgrades.html", “body” : “¥u003cp¥u003e¥u003cspan¥u003eWe are excited to announce that Six Apart has acquired Topics, a dynamic online publishing product. This offering will provide Six Apart customers with an easy and cost-effective way to adapt existing content to evolving digital platforms.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eThis new product will save Six Apart customers a significant amount of time and money by allowing users to upgrade their websites and applications without migrating from their current content management systems. Clients who need to scale large amounts of data or even revamp a website on an entirely new platform can now achieve these changes with minimal effort.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eSix Apart customers will benefit not only from saved time and money, but also from ease of use. Topics does not have a user interface, so there is no new software to learn. Instead, it exists as a middle layer between the data library and the published page - automatically gathering, organizing and redistributing data.¥u003c/span¥u003e¥u003c/p¥u003e”, “keywords” : “”, “allowTrackbacks” : false, “id” : 5, “trackbacks” : [], “modifiedDate” : “2014-11-14T13:17:52¥u002b09:00”, “trackbackCount” : “0”, “folder” : { “id” : 2, “parent” : 1, “label” : “news” }, “blog” : { “id” : “1” }, “commentCount” : “0”, “tags” : [], “basename” : “six_apart_acquires_topics_server_to_simplify_site_upgrades”, “assets” : [], “pingsSentUrl” : [], “title” : “Six Apart Acquires Topics Server to Simplify Site Upgrades”, “class” : “entry”, “createdDate” : “2014-11-14T13:17:52¥u002b09:00”, “more” : “”, “customFields” : [ { “basename” : “place”, “value” : “New York City” }, { “basename” : “agenda”, “value” : “Movable Type¥nTopics” } ] }

Pages

Retrieve a list of pages
GET/sites/{site_id}/pages{?search,searchFields,limit,offset,sortBy,sortOrder,fields,includeIds,excludeIds,status,maxComments,maxTrackbacks,no_text_filter,dateField,dateFrom,dateTo}

Retrieve a list of pages.

Authentication required if want to include unpublished pages.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to retrieve the list of pages.
404 Not Found Site not found.

Permissions

  • manage_pages
    • for retrieve unpublished page

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/pages?search=&searchFields=&limit=&offset=&sortBy=&sortOrder=&fields=&includeIds=&excludeIds=&status=&maxComments=&maxTrackbacks=&no_text_filter=&dateField=&dateFrom=&dateTo=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

search
string (optional) 

Search query.

searchFields
string (optional) Default: title,body,more,keywords,excerpt,basename 

The comma separated field name list to search.

limit
number (optional) Default: 10 

Maximum number of pages to retrieve.

offset
number (optional) Default: 0 

0-indexed offset.

sortBy
string (optional) Default: modified_on 

The field name for sort. You can specify one of following values

  • authored_on
  • title
  • created_on
  • modified_on

sortOrder
string (optional) Default: descend 
descend
(default) Return pages in descending order.
ascend
Return pages in ascending order.
fields
string (optional) 

The field list to retrieve as part of the Pages resource. That list should be separated by comma. If this parameter is not specified, All fields will be returned.

includeIds
string (optional) 

The comma separated ID list of pages to include to result.

excludeIds
string (optional) 

The comma separated ID list of pages to exclude from result.

status
string (optional) 

Filter by container page’s status.

Draft
status is 1.
Publish
status is 2.
Review
status is 3.
Future
status is 4.
Spam
status is 5.

maxComments
number (optional) 

This is an optional parameter. Maximum number of pages to retrieve as part of the Pages resource. If this parameter is not supplied, no pages will be returned.

maxTrackbacks
number (optional) 

This is an optional parameter. Maximum number of received trackbacks to retrieve as part of the Pages resource. If this parameter is not supplied, no trackbacks will be returned.

no_text_filter
number (optional) Default: 0 

If you want to fetch the raw text, set to ‘1’. New in v2

dateField
string (optional) Default: created_on 

Specifies the field name to be used as a date field for filtering. (new in v3)

dateFrom
string (optional) 

The start date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

dateTo
string (optional) 

The end date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults": 1,
  "items": [
    {
      "excerpt": "We are excited to announce that Six Apar...",
      "status": "Publish",
      "date": "2014-11-14T13:08:42¥u002b09:00",
      "updatable": false,
      "author": {
        "userpicUrl": null,
        "displayName": "Yuji Takayama"
      },
      "allowComments": true,
      "comments": [],
      "permalink": "http://localhost/news/six-apart-acquires-topics-server-to-simplify-site-upgrades.html",
      "body": "¥u003cp¥u003e¥u003cspan¥u003eWe are excited to announce that Six Apart has acquired Topics, a dynamic online publishing product. This offering will provide Six Apart customers with an easy and cost-effective way to adapt existing content to evolving digital platforms.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eThis new product will save Six Apart customers a significant amount of time and money by allowing users to upgrade their websites and applications without migrating from their current content management systems. Clients who need to scale large amounts of data or even revamp a website on an entirely new platform can now achieve these changes with minimal effort.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eSix Apart customers will benefit not only from saved time and money, but also from ease of use. Topics does not have a user interface, so there is no new software to learn. Instead, it exists as a middle layer between the data library and the published page - automatically gathering, organizing and redistributing data.¥u003c/span¥u003e¥u003c/p¥u003e",
      "keywords": "",
      "allowTrackbacks": false,
      "id": 5,
      "trackbacks": [],
      "modifiedDate": "2014-11-14T13:17:52¥u002b09:00",
      "trackbackCount": "0",
      "folder": {
        "id": 2,
        "parent": 1,
        "label": "news"
      },
      "blog": {
        "id": "1"
      },
      "commentCount": "0",
      "tags": [],
      "basename": "six_apart_acquires_topics_server_to_simplify_site_upgrades",
      "assets": [],
      "pingsSentUrl": [],
      "title": "Six Apart Acquires Topics Server to Simplify Site Upgrades",
      "class": "entry",
      "createdDate": "2014-11-14T13:17:52¥u002b09:00",
      "more": "",
      "customFields": [
        {
          "basename": "place",
          "value": "New York City"
        },
        {
          "basename": "agenda",
          "value": "Movable Type¥nTopics"
        }
      ]
    }
  ]
}

Retrieve a list of pages by folder
GET/sites/{site_id}/folders/{folder_id}/pages{?search,searchFields,limit,offset,sortBy,sortOrder,fields,includeIds,excludeIds,status,maxComments,maxTrackbacks,no_text_filter,dateField,dateFrom,dateTo}

Retrieve a list of pages by folder.

Authentication required if want to include unpublished pages.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to retrieve the list of pages.
404 Not Found Site or Folder not found.

Permissions

  • manage_pages
    • for retrieve unpublished page

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/folders/folder_id/pages?search=&searchFields=&limit=&offset=&sortBy=&sortOrder=&fields=&includeIds=&excludeIds=&status=&maxComments=&maxTrackbacks=&no_text_filter=&dateField=&dateFrom=&dateTo=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

folder_id
number (required) 

The folder ID.

search
string (optional) 

Search query.

searchFields
string (optional) Default: title,body,more,keywords,excerpt,basename 

The comma separated field name list to search.

limit
number (optional) Default: 10 

Maximum number of pages to retrieve.

offset
number (optional) Default: 0 

0-indexed offset.

sortBy
string (optional) Default: modified_on 

The field name for sort. You can specify one of following values

  • authored_on
  • title
  • created_on
  • modified_on

sortOrder
string (optional) Default: descend 
descend
(default) Return pages in descending order.
ascend
Return pages in ascending order.
fields
string (optional) 

The field list to retrieve as part of the Pages resource. That list should be separated by comma. If this parameter is not specified, All fields will be returned.

includeIds
string (optional) 

The comma separated ID list of pages to include to result.

excludeIds
string (optional) 

The comma separated ID list of pages to exclude from result.

status
string (optional) 

Filter by container page’s status.

Draft
status is 1.
Publish
status is 2.
Review
status is 3.
Future
status is 4.
Spam
status is 5.

maxComments
number (optional) 

This is an optional parameter. Maximum number of comments to retrieve as part of the Pages resource. If this parameter is not supplied, no comments will be returned.

maxTrackbacks
number (optional) 

This is an optional parameter. Maximum number of received trackbacks to retrieve as part of the Pages resource. If this parameter is not supplied, no trackbacks will be returned.

no_text_filter
number (optional) Default: 0 

If you want to fetch the raw text, set to ‘1’. New in v2

dateField
string (optional) Default: created_on 

Specifies the field name to be used as a date field for filtering. (new in v3)

dateFrom
string (optional) 

The start date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

dateTo
string (optional) 

The end date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults": 1,
  "items": [
    {
      "excerpt": "We are excited to announce that Six Apar...",
      "status": "Publish",
      "date": "2014-11-14T13:08:42¥u002b09:00",
      "updatable": false,
      "author": {
        "userpicUrl": null,
        "displayName": "Yuji Takayama"
      },
      "allowComments": true,
      "comments": [],
      "permalink": "http://localhost/news/six-apart-acquires-topics-server-to-simplify-site-upgrades.html",
      "body": "¥u003cp¥u003e¥u003cspan¥u003eWe are excited to announce that Six Apart has acquired Topics, a dynamic online publishing product. This offering will provide Six Apart customers with an easy and cost-effective way to adapt existing content to evolving digital platforms.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eThis new product will save Six Apart customers a significant amount of time and money by allowing users to upgrade their websites and applications without migrating from their current content management systems. Clients who need to scale large amounts of data or even revamp a website on an entirely new platform can now achieve these changes with minimal effort.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eSix Apart customers will benefit not only from saved time and money, but also from ease of use. Topics does not have a user interface, so there is no new software to learn. Instead, it exists as a middle layer between the data library and the published page - automatically gathering, organizing and redistributing data.¥u003c/span¥u003e¥u003c/p¥u003e",
      "keywords": "",
      "allowTrackbacks": false,
      "id": 5,
      "trackbacks": [],
      "modifiedDate": "2014-11-14T13:17:52¥u002b09:00",
      "trackbackCount": "0",
      "folder": {
        "id": 2,
        "parent": 1,
        "label": "news"
      },
      "blog": {
        "id": "1"
      },
      "commentCount": "0",
      "tags": [],
      "basename": "six_apart_acquires_topics_server_to_simplify_site_upgrades",
      "assets": [],
      "pingsSentUrl": [],
      "title": "Six Apart Acquires Topics Server to Simplify Site Upgrades",
      "class": "entry",
      "createdDate": "2014-11-14T13:17:52¥u002b09:00",
      "more": "",
      "customFields": [
        {
          "basename": "place",
          "value": "New York City"
        },
        {
          "basename": "agenda",
          "value": "Movable Type¥nTopics"
        }
      ]
    }
  ]
}

Retrieve a list of pages that related with asset
GET/sites/{site_id}/assets/{asset_id}/pages{?search,searchFields,limit,offset,sortBy,sortOrder,fields,includeIds,excludeIds,status,maxComments,maxTrackbacks,no_text_filter,dateField,dateFrom,dateTo}

Retrieve a list of pages that related with asset.

Authentication required if want to include unpublished pages.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to retrieve the list of pages.
404 Not Found Site or Asset not found.

Permissions

  • manage_pages
    • for retrieve unpublished page

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/assets/asset_id/pages?search=&searchFields=&limit=&offset=&sortBy=&sortOrder=&fields=&includeIds=&excludeIds=&status=&maxComments=&maxTrackbacks=&no_text_filter=&dateField=&dateFrom=&dateTo=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

asset_id
number (required) 

The asset ID.

search
string (optional) 

Search query.

searchFields
string (optional) Default: title,body,more,keywords,excerpt,basename 

The comma separated field name list to search.

limit
number (optional) Default: 10 

Maximum number of pages to retrieve.

offset
number (optional) Default: 0 

0-indexed offset.

sortBy
string (optional) Default: authored_on 

The field name for sort. You can specify one of following values

  • authored_on
  • title
  • created_on
  • modified_on

sortOrder
string (optional) Default: descend 
descend
(default) Return pages in descending order.
ascend
Return pages in ascending order.
fields
string (optional) 

The field list to retrieve as part of the Pages resource. That list should be separated by comma. If this parameter is not specified, All fields will be returned.

includeIds
string (optional) 

The comma separated ID list of pages to include to result.

excludeIds
string (optional) 

The comma separated ID list of pages to exclude from result.

status
string (optional) 

Filter by container entry’s status.

Draft
entry_status is 1.
Publish
entry_status is 2.
Review
entry_status is 3.
Future
entry_status is 4.
Spam
entry_status is 5.

maxComments
number (optional) 

This is an optional parameter. Maximum number of pages to retrieve as part of the Pages resource. If this parameter is not supplied, no pages will be returned.

maxTrackbacks
number (optional) 

This is an optional parameter. Maximum number of received trackbacks to retrieve as part of the Pages resource. If this parameter is not supplied, no trackbacks will be returned.

no_text_filter
number (optional) Default: 0 

If you want to fetch the raw text, set to ‘1’. New in v2

dateField
string (optional) Default: created_on 

Specifies the field name to be used as a date field for filtering. (new in v3)

dateFrom
string (optional) 

The start date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

dateTo
string (optional) 

The end date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults": 1,
  "items": [
    {
      "excerpt": "We are excited to announce that Six Apar...",
      "status": "Publish",
      "date": "2014-11-14T13:08:42¥u002b09:00",
      "updatable": false,
      "author": {
        "userpicUrl": null,
        "displayName": "Yuji Takayama"
      },
      "allowComments": true,
      "comments": [],
      "permalink": "http://localhost/blog/20141114-1/2014/11/six-apart-acquires-topics-server-to-simplify-site-upgrades.html",
      "body": "¥u003cp¥u003e¥u003cspan¥u003eWe are excited to announce that Six Apart has acquired Topics, a dynamic online publishing product. This offering will provide Six Apart customers with an easy and cost-effective way to adapt existing content to evolving digital platforms.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eThis new product will save Six Apart customers a significant amount of time and money by allowing users to upgrade their websites and applications without migrating from their current content management systems. Clients who need to scale large amounts of data or even revamp a website on an entirely new platform can now achieve these changes with minimal effort.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eSix Apart customers will benefit not only from saved time and money, but also from ease of use. Topics does not have a user interface, so there is no new software to learn. Instead, it exists as a middle layer between the data library and the published page - automatically gathering, organizing and redistributing data.¥u003c/span¥u003e¥u003c/p¥u003e",
      "keywords": "",
      "allowTrackbacks": false,
      "id": 5,
      "trackbacks": [],
      "modifiedDate": "2014-11-14T13:17:52¥u002b09:00",
      "trackbackCount": "0",
      "folder": {
        "id": 2,
        "parent": 1,
        "label": "news"
      },
      "blog": {
        "id": "1"
      },
      "commentCount": "0",
      "tags": [],
      "basename": "six_apart_acquires_topics_server_to_simplify_site_upgrades",
      "assets": [],
      "pingsSentUrl": [],
      "title": "Six Apart Acquires Topics Server to Simplify Site Upgrades",
      "class": "entry",
      "createdDate": "2014-11-14T13:17:52¥u002b09:00",
      "more": "",
      "customFields": [
        {
          "basename": "place",
          "value": "New York City"
        },
        {
          "basename": "agenda",
          "value": "Movable Type¥nTopics"
        }
      ]
    }
  ]
}

Retrieve a list of pages that related with tag
GET/sites/{site_id}/tags/{tag_id}/pages{?search,searchFields,limit,offset,sortBy,sortOrder,fields,includeIds,excludeIds,status,maxComments,maxTrackbacks,no_text_filter,dateField,dateFrom,dateTo}

Retrieve a list of pages that related with tag.

Authentication required if want to include unpublished pages.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to retrieve the list of pages.
404 Not Found Site or Tag not found.

Permissions

  • manage_pages
    • for retrieve unpublished page

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/tags/tag_id/pages?search=&searchFields=&limit=&offset=&sortBy=&sortOrder=&fields=&includeIds=&excludeIds=&status=&maxComments=&maxTrackbacks=&no_text_filter=&dateField=&dateFrom=&dateTo=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

tag_id
number (required) 

The tag ID.

search
string (optional) 

Search query.

searchFields
string (optional) Default: title,body,more,keywords,excerpt,basename 

The comma separated field name list to search.

limit
number (optional) Default: 10 

Maximum number of pages to retrieve.

offset
number (optional) Default: 0 

0-indexed offset.

sortBy
string (optional) Default: modified_on 

The field name for sort. You can specify one of following values

  • authored_on
  • title
  • created_on
  • modified_on

sortOrder
string (optional) Default: descend 
descend
(default) Return pages in descending order.
ascend
Return pages in ascending order.
fields
string (optional) 

The field list to retrieve as part of the Pages resource. That list should be separated by comma. If this parameter is not specified, All fields will be returned.

includeIds
string (optional) 

The comma separated ID list of pages to include to result.

excludeIds
string (optional) 

The comma separated ID list of pages to exclude from result.

status
string (optional) 

Filter by container entry’s status.

Draft
entry_status is 1.
Publish
entry_status is 2.
Review
entry_status is 3.
Future
entry_status is 4.
Spam
entry_status is 5.

maxComments
number (optional) 

This is an optional parameter. Maximum number of pages to retrieve as part of the Pages resource. If this parameter is not supplied, no pages will be returned.

maxTrackbacks
number (optional) 

This is an optional parameter. Maximum number of received trackbacks to retrieve as part of the Pages resource. If this parameter is not supplied, no trackbacks will be returned.

no_text_filter
number (optional) Default: 0 

If you want to fetch the raw text, set to ‘1’.

dateField
string (optional) Default: created_on 

Specifies the field name to be used as a date field for filtering. (new in v3)

dateFrom
string (optional) 

The start date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

dateTo
string (optional) 

The end date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults": 1,
  "items": [
    {
      "excerpt": "We are excited to announce that Six Apar...",
      "status": "Publish",
      "date": "2014-11-14T13:08:42¥u002b09:00",
      "updatable": false,
      "author": {
        "userpicUrl": null,
        "displayName": "Yuji Takayama"
      },
      "allowComments": true,
      "comments": [],
      "permalink": "http://localhost/blog/20141114-1/2014/11/six-apart-acquires-topics-server-to-simplify-site-upgrades.html",
      "body": "¥u003cp¥u003e¥u003cspan¥u003eWe are excited to announce that Six Apart has acquired Topics, a dynamic online publishing product. This offering will provide Six Apart customers with an easy and cost-effective way to adapt existing content to evolving digital platforms.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eThis new product will save Six Apart customers a significant amount of time and money by allowing users to upgrade their websites and applications without migrating from their current content management systems. Clients who need to scale large amounts of data or even revamp a website on an entirely new platform can now achieve these changes with minimal effort.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eSix Apart customers will benefit not only from saved time and money, but also from ease of use. Topics does not have a user interface, so there is no new software to learn. Instead, it exists as a middle layer between the data library and the published page - automatically gathering, organizing and redistributing data.¥u003c/span¥u003e¥u003c/p¥u003e",
      "keywords": "",
      "allowTrackbacks": false,
      "id": 5,
      "trackbacks": [],
      "modifiedDate": "2014-11-14T13:17:52¥u002b09:00",
      "trackbackCount": "0",
      "folder": {
        "id": 2,
        "parent": 1,
        "label": "news"
      },
      "blog": {
        "id": "1"
      },
      "commentCount": "0",
      "tags": [],
      "basename": "six_apart_acquires_topics_server_to_simplify_site_upgrades",
      "assets": [],
      "pingsSentUrl": [],
      "title": "Six Apart Acquires Topics Server to Simplify Site Upgrades",
      "class": "entry",
      "createdDate": "2014-11-14T13:17:52¥u002b09:00",
      "more": "",
      "customFields": [
        {
          "basename": "place",
          "value": "New York City"
        },
        {
          "basename": "agenda",
          "value": "Movable Type¥nTopics"
        }
      ]
    }
  ]
}

Create a new page
POST/sites/{site_id}/pages

Create a new page.

Authentication required.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to create a new page.
404 Not Found Site not found.

Permissions

  • manage_post

Request Body Parameters

Name Type Required Default Description
page Object Yes Single Pages resource

Example URI

POST http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/pages
URI Parameters
HideShow
site_id
number (required) 

The site ID.

Request  Pages resource
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "excerpt": "We are excited to announce that Six Apar...",
  "status": "Publish",
  "date": "2014-11-14T13:08:42¥u002b09:00",
  "updatable": false,
  "author": {
    "userpicUrl": null,
    "displayName": "Yuji Takayama"
  },
  "allowComments": true,
  "comments": [],
  "permalink": "http://localhost/blog/20141114-1/2014/11/six-apart-acquires-topics-server-to-simplify-site-upgrades.html",
  "body": "¥u003cp¥u003e¥u003cspan¥u003eWe are excited to announce that Six Apart has acquired Topics, a dynamic online publishing product. This offering will provide Six Apart customers with an easy and cost-effective way to adapt existing content to evolving digital platforms.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eThis new product will save Six Apart customers a significant amount of time and money by allowing users to upgrade their websites and applications without migrating from their current content management systems. Clients who need to scale large amounts of data or even revamp a website on an entirely new platform can now achieve these changes with minimal effort.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eSix Apart customers will benefit not only from saved time and money, but also from ease of use. Topics does not have a user interface, so there is no new software to learn. Instead, it exists as a middle layer between the data library and the published page - automatically gathering, organizing and redistributing data.¥u003c/span¥u003e¥u003c/p¥u003e",
  "keywords": "",
  "allowTrackbacks": false,
  "id": 5,
  "trackbacks": [],
  "modifiedDate": "2014-11-14T13:17:52¥u002b09:00",
  "trackbackCount": "0",
  "folder": {
    "id": 2,
    "parent": 1,
    "label": "news"
  },
  "blog": {
    "id": "1"
  },
  "commentCount": "0",
  "tags": [],
  "basename": "six_apart_acquires_topics_server_to_simplify_site_upgrades",
  "assets": [],
  "pingsSentUrl": [],
  "title": "Six Apart Acquires Topics Server to Simplify Site Upgrades",
  "class": "entry",
  "createdDate": "2014-11-14T13:17:52¥u002b09:00",
  "more": "",
  "customFields": [
    {
      "basename": "place",
      "value": "New York City"
    },
    {
      "basename": "agenda",
      "value": "Movable Type¥nTopics"
    }
  ]
}

Retrieve a single page by its ID
GET/sites/{site_id}/pages/{page_id}{?fields}

Retrieve a single page by its ID.

Authentication required if the page status is “unpublished”.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to retrieve the requested page.
404 Not Found Site or Page not found.

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/pages/page_id?fields=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

page_id
number (required) 

The page ID.

fields
string (optional) 

The field list to retrieve as part of the Pages resource. That list should be separated by comma. If this parameter is not specified, All fields will be returned.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "excerpt": "We are excited to announce that Six Apar...",
  "status": "Publish",
  "date": "2014-11-14T13:08:42¥u002b09:00",
  "updatable": false,
  "author": {
    "userpicUrl": null,
    "displayName": "Yuji Takayama"
  },
  "allowComments": true,
  "comments": [],
  "permalink": "http://localhost/blog/20141114-1/2014/11/six-apart-acquires-topics-server-to-simplify-site-upgrades.html",
  "body": "¥u003cp¥u003e¥u003cspan¥u003eWe are excited to announce that Six Apart has acquired Topics, a dynamic online publishing product. This offering will provide Six Apart customers with an easy and cost-effective way to adapt existing content to evolving digital platforms.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eThis new product will save Six Apart customers a significant amount of time and money by allowing users to upgrade their websites and applications without migrating from their current content management systems. Clients who need to scale large amounts of data or even revamp a website on an entirely new platform can now achieve these changes with minimal effort.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eSix Apart customers will benefit not only from saved time and money, but also from ease of use. Topics does not have a user interface, so there is no new software to learn. Instead, it exists as a middle layer between the data library and the published page - automatically gathering, organizing and redistributing data.¥u003c/span¥u003e¥u003c/p¥u003e",
  "keywords": "",
  "allowTrackbacks": false,
  "id": 5,
  "trackbacks": [],
  "modifiedDate": "2014-11-14T13:17:52¥u002b09:00",
  "trackbackCount": "0",
  "folder": {
    "id": 2,
    "parent": 1,
    "label": "news"
  },
  "blog": {
    "id": "1"
  },
  "commentCount": "0",
  "tags": [],
  "basename": "six_apart_acquires_topics_server_to_simplify_site_upgrades",
  "assets": [],
  "pingsSentUrl": [],
  "title": "Six Apart Acquires Topics Server to Simplify Site Upgrades",
  "class": "entry",
  "createdDate": "2014-11-14T13:17:52¥u002b09:00",
  "more": "",
  "customFields": [
    {
      "basename": "place",
      "value": "New York City"
    },
    {
      "basename": "agenda",
      "value": "Movable Type¥nTopics"
    }
  ]
}

Update an existing page
PUT/sites/{site_id}/pages/{page_id}

Update an existing page.

Authentication required.

This method accepts PUT and POST with __method=PUT.

** Update in v2.0 **

  • You can attach/detach folder and assets in the one request.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to update the speciied age.
404 Not Found Site or Pagenot found.

Permissions

  • manage_pages

Example URI

PUT http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/pages/page_id
URI Parameters
HideShow
site_id
number (required) 

The site ID.

page_id
number (required) 

The page ID.

Request  Entries resource
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Body
page={"excerpt" : "We are excited to announce that Six Apar...","status" : "Publish","allowComments" : true,"body" : "¥u003cp¥u003e¥u003cspan¥u003eWe are excited to announce that Six Apart has acquired Topics, a dynamic online publishing product. This offering will provide Six Apart customers with an easy and cost-effective way to adapt existing content to evolving digital platforms.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eThis new product will save Six Apart customers a significant amount of time and money by allowing users to upgrade their websites and applications without migrating from their current content management systems. Clients who need to scale large amounts of data or even revamp a website on an entirely new platform can now achieve these changes with minimal effort.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eSix Apart customers will benefit not only from saved time and money, but also from ease of use. Topics does not have a user interface, so there is no new software to learn. Instead, it exists as a middle layer between the data library and the published page - automatically gathering, organizing and redistributing data.¥u003c/span¥u003e¥u003c/p¥u003e","keywords" : "","allowTrackbacks" : false,"basename" : "six_apart_acquires_topics_server_to_simplify_site_upgrades","title" : "Six Apart Acquires Topics Server to Simplify Site Upgrades","more" : "","customFields" : [{"basename" : "place","value" : "New York City"},{"basename" : "agenda","value" : "Movable Type¥nTopics"}]}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "excerpt": "We are excited to announce that Six Apar...",
  "status": "Publish",
  "date": "2014-11-14T13:08:42¥u002b09:00",
  "updatable": false,
  "author": {
    "userpicUrl": null,
    "displayName": "Yuji Takayama"
  },
  "allowComments": true,
  "comments": [],
  "permalink": "http://localhost/blog/20141114-1/2014/11/six-apart-acquires-topics-server-to-simplify-site-upgrades.html",
  "body": "¥u003cp¥u003e¥u003cspan¥u003eWe are excited to announce that Six Apart has acquired Topics, a dynamic online publishing product. This offering will provide Six Apart customers with an easy and cost-effective way to adapt existing content to evolving digital platforms.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eThis new product will save Six Apart customers a significant amount of time and money by allowing users to upgrade their websites and applications without migrating from their current content management systems. Clients who need to scale large amounts of data or even revamp a website on an entirely new platform can now achieve these changes with minimal effort.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eSix Apart customers will benefit not only from saved time and money, but also from ease of use. Topics does not have a user interface, so there is no new software to learn. Instead, it exists as a middle layer between the data library and the published page - automatically gathering, organizing and redistributing data.¥u003c/span¥u003e¥u003c/p¥u003e",
  "keywords": "",
  "allowTrackbacks": false,
  "id": 5,
  "trackbacks": [],
  "modifiedDate": "2014-11-14T13:17:52¥u002b09:00",
  "trackbackCount": "0",
  "folder": {
    "id": 2,
    "parent": 1,
    "label": "news"
  },
  "blog": {
    "id": "1"
  },
  "commentCount": "0",
  "tags": [],
  "basename": "six_apart_acquires_topics_server_to_simplify_site_upgrades",
  "assets": [],
  "pingsSentUrl": [],
  "title": "Six Apart Acquires Topics Server to Simplify Site Upgrades",
  "class": "entry",
  "createdDate": "2014-11-14T13:17:52¥u002b09:00",
  "more": "",
  "customFields": [
    {
      "basename": "place",
      "value": "New York City"
    },
    {
      "basename": "agenda",
      "value": "Movable Type¥nTopics"
    }
  ]
}

Delete an existing page
DELETE/sites/{site_id}/pages/{page_id}

Delete an existing page.

Authentication required.

This method accepts PUT and POST with __method=DELETE.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to delete the speciied page.
404 Not Found Site or Page not found.

Permissions

  • edit_entry

Example URI

DELETE http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/pages/page_id
URI Parameters
HideShow
site_id
number (required) 

The site ID.

page_id
number (required) 

The page ID.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "excerpt": "We are excited to announce that Six Apar...",
  "status": "Publish",
  "date": "2014-11-14T13:08:42¥u002b09:00",
  "updatable": false,
  "author": {
    "userpicUrl": null,
    "displayName": "Yuji Takayama"
  },
  "allowComments": true,
  "comments": [],
  "permalink": "http://localhost/blog/20141114-1/2014/11/six-apart-acquires-topics-server-to-simplify-site-upgrades.html",
  "body": "¥u003cp¥u003e¥u003cspan¥u003eWe are excited to announce that Six Apart has acquired Topics, a dynamic online publishing product. This offering will provide Six Apart customers with an easy and cost-effective way to adapt existing content to evolving digital platforms.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eThis new product will save Six Apart customers a significant amount of time and money by allowing users to upgrade their websites and applications without migrating from their current content management systems. Clients who need to scale large amounts of data or even revamp a website on an entirely new platform can now achieve these changes with minimal effort.¥u003c/span¥u003e¥u003c/p¥u003e¥n¥u003cp¥u003e¥u003cspan¥u003eSix Apart customers will benefit not only from saved time and money, but also from ease of use. Topics does not have a user interface, so there is no new software to learn. Instead, it exists as a middle layer between the data library and the published page - automatically gathering, organizing and redistributing data.¥u003c/span¥u003e¥u003c/p¥u003e",
  "keywords": "",
  "allowTrackbacks": false,
  "id": 5,
  "trackbacks": [],
  "modifiedDate": "2014-11-14T13:17:52¥u002b09:00",
  "trackbackCount": "0",
  "folder": {
    "id": 2,
    "parent": 1,
    "label": "news"
  },
  "blog": {
    "id": "1"
  },
  "commentCount": "0",
  "tags": [],
  "basename": "six_apart_acquires_topics_server_to_simplify_site_upgrades",
  "assets": [],
  "pingsSentUrl": [],
  "title": "Six Apart Acquires Topics Server to Simplify Site Upgrades",
  "class": "entry",
  "createdDate": "2014-11-14T13:17:52¥u002b09:00",
  "more": "",
  "customFields": [
    {
      "basename": "place",
      "value": "New York City"
    },
    {
      "basename": "agenda",
      "value": "Movable Type¥nTopics"
    }
  ]
}

previewPage

Make a preview by specified data
POST/sites/{site_id}/pages/preview{?raw}

Make a preview by specified data.

Authentication required.

  • This endpoint is available in Movable Type 6.1.2 or later.

Permissions

  • manage_pages

Example URI

POST http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/pages/preview?raw=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

raw
number (optional) 

If specify “1”, will be returned preview contents.

Request  Entries resource
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Body
page={ "title" : "My First Post", "body" : "This is my first post!" }
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": "success",
  "preview": "http://example.com/my-first-post.html"
}
Response  403
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Do not have permission to get page preview.",
    "code": "403"
  }
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Site not found",
    "code": "404"
  }
}
Response  500
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Some error message is here",
    "code": "500"
  }
}

Make a preview for exising data
POST/sites/{site_id}/pages/{page_id}/preview{?raw}

Make a preview for exising data.

  • Authentication required.
  • This endpoint is available in Movable Type 6.1.2 or later.
  • page parameter is required. If you just want to get preview page from existing data, you should provide page parameter with empty json.

Permissions

  • manage_post

Example URI

POST http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/pages/page_id/preview?raw=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

page_id
number (required) 

The page ID.

raw
number (optional) 

If specify “1”, will be returned preview contents.

Request  Templates resource
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Body
page={}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": "success",
  "preview": "http://example.com/existing-page.html"
}
Response  403
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Do not have permission to get entry preview.",
    "code": "403"
  }
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Site not found / Page not found",
    "code": "404"
  }
}
Response  500
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Some error message is here",
    "code": "500"
  }
}

Permissions

This is the Permissions resource. In this case, Permission means Association record.

Property Name Type Data Type Database Column Private Read Only Description Version
blog Ojbect Blog Y The blog of this permission. v2
blog.id value number mt_permission.permission_blog_id Y The ID of the blog. v1
id value number mt_permission.permission_id Y The ID for this permission. v2
createdBy Object User Y Created user of this permission. v2
createdBy.displayName value string mt_author.author_nickname Y The display name of this permission creator. v2
createdBy.id value number mt_permission.permission_created_by Y The ID of this permission creator. v2
createdBy.userpicUrl value string mt_author.author_userpic_url Y The URL of this permission creator’s userpic. The userpic will be made by UserpicThumbnailSize and UserpicAllowRect settings. If user does not set own userpic, will be returned empty string. v2
createdDate value iso 8601 datetime mt_permission.permission_created_on Y Created date of this permission. v2
permissions ARRAY string mt_permission.permission_permissions, mt_permission.permissoin_restrictions Y The list of granted permissions. The restricted permissions are excluded from this list. v2
roles ARRAY Role Y The list of roles. v2
role.id value number mt_role.role_id Y The ID of this role. v2
role.name value string mt_role.role_name Y The name of this role. v2
user Object User Y The user of this permission. v2
user.displayName value string mt_author.author_nickname Y The nickname for this permission user. v2
user.id value number mt_permission.permission_author_id Y The ID for this permission user. v2
user.userpicUrl value string mt_author.author_userpic_url Y The URL of this permission user’s userpic. The userpic will be made by UserpicThumbnailSize and UserpicAllowRect settings. If user does not set own userpic, will be returned empty string. v2

{ “roles” : [ { “name” : “Website Administrator”, “id” : 1 } ], “permissions” : [ “administer”, “administer_blog”, “administer_website”, “comment”, “create_blog”, “create_post”, “create_website”, “edit_all_posts”, “edit_assets”, “edit_categories”, “edit_config”, “edit_notifications”, “edit_tags”, “edit_templates”, “manage_feedback”, “manage_member_blogs”, “manage_pages”, “manage_plugins”, “manage_themes”, “manage_users”, “publish_post”, “rebuild”, “save_image_defaults”, “send_notifications”, “set_publish_paths”, “upload”, “view_blog_log”, “view_log” ], “createdBy” : { “userpicUrl” : null, “id” : “1”, “displayName” : “Yuji Takayama” }, “user” : { “userpicUrl” : null, “id” : “1”, “displayName” : “Yuji Takayama” }, “blog” : { “id” : “2” }, “id” : “3”, “createdDate” : “2015-03-21T19:37:53+09:00” }

List Permissions

Retrieve a list of permissions
GET/permissions{?limit,offset,sortBy,sortOrder,fields,blogIds,dateField,dateFrom,dateTo}

Retrieve a list of permissions. Only system administrator can call this endpoint.

Authentication required

Permissions

  • Administer

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/permissions?limit=&offset=&sortBy=&sortOrder=&fields=&blogIds=&dateField=&dateFrom=&dateTo=
URI Parameters
HideShow
limit
number (optional) Default: 25 

Maximum number of permissions to retrieve.

offset
number (optional) Default: 0 

0-indexed offset.

sortBy
string (optional) Default: bog_id 

The field name for sort. You can specify one of following values

  • id
  • blog_id
  • author_id
  • created_by
  • created_on

sortOrder
string (optional) Default: ascend 
descend
(default) Return permissions in descending order.
ascend
Return permissions in ascending order.
fields
string (optional) 

The field list to retrieve as part of the Permissions resource. That list should be separated by comma. If this parameter is not specified, All fields will be returned.

blogIds
number (optional) 

The comma-separated blog id list that to be included in the result.

dateField
string (optional) Default: created_on 

Specifies the field name to be used as a date field for filtering. (new in v3)

dateFrom
string (optional) 

The start date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

dateTo
string (optional) 

The end date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

Request
HideShow
Headers
X-MT-Authorization: MTAuth accessToken=<Token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults": 1,
  "items": [
    {
      "roles": [
        {
          "name": "Website Administrator",
          "id": 1
        }
      ],
      "permissions": [
        "administer",
        "administer_blog",
        "administer_website",
        "comment",
        "create_blog",
        "create_post",
        "create_website",
        "edit_all_posts",
        "edit_assets",
        "edit_categories",
        "edit_config",
        "edit_notifications",
        "edit_tags",
        "edit_templates",
        "manage_feedback",
        "manage_member_blogs",
        "manage_pages",
        "manage_plugins",
        "manage_themes",
        "manage_users",
        "publish_post",
        "rebuild",
        "save_image_defaults",
        "send_notifications",
        "set_publish_paths",
        "upload",
        "view_blog_log",
        "view_log"
      ],
      "createdBy": {
        "userpicUrl": null,
        "id": "1",
        "displayName": "Yuji Takayama"
      },
      "user": {
        "userpicUrl": null,
        "id": "1",
        "displayName": "Yuji Takayama"
      },
      "blog": {
        "id": "2"
      },
      "id": "3",
      "createdDate": "2015-03-21T19:37:53+09:00"
    }
  ]
}

Retrieve a list of permissions by user
GET/users/{user_id}/permissions{?limit,offset,sortBy,sortOrder,fields,blogIds,dateField,dateFrom,dateTo}

Retrieve a list of permissions by user.

Authentication required

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/users/user_id/permissions?limit=&offset=&sortBy=&sortOrder=&fields=&blogIds=&dateField=&dateFrom=&dateTo=
URI Parameters
HideShow
user_id
number or the word 'me' (required) 

The user ID.

limit
number (optional) Default: 25 

Maximum number of permissions to retrieve.

offset
number (optional) Default: 0 

0-indexed offset.

sortBy
string (optional) Default: bog_id 

The field name for sort. You can specify one of following values

  • id
  • blog_id
  • author_id
  • created_by
  • created_on

sortOrder
string (optional) Default: ascend 
descend
(default) Return permissions in descending order.
ascend
Return permissions in ascending order.
fields
string (optional) 

The field list to retrieve as part of the Permissions resource. That list should be separated by comma. If this parameter is not specified, All fields will be returned.

blogIds
number (optional) 

The comma-separated blog id list that to be included in the result.

dateField
string (optional) Default: created_on 

Specifies the field name to be used as a date field for filtering. (new in v3)

dateFrom
string (optional) 

The start date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

dateTo
string (optional) 

The end date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

Request
HideShow
Headers
X-MT-Authorization: MTAuth accessToken=<Token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults": 1,
  "items": [
    {
      "roles": [
        {
          "name": "Website Administrator",
          "id": 1
        }
      ],
      "permissions": [
        "administer",
        "administer_blog",
        "administer_website",
        "comment",
        "create_blog",
        "create_post",
        "create_website",
        "edit_all_posts",
        "edit_assets",
        "edit_categories",
        "edit_config",
        "edit_notifications",
        "edit_tags",
        "edit_templates",
        "manage_feedback",
        "manage_member_blogs",
        "manage_pages",
        "manage_plugins",
        "manage_themes",
        "manage_users",
        "publish_post",
        "rebuild",
        "save_image_defaults",
        "send_notifications",
        "set_publish_paths",
        "upload",
        "view_blog_log",
        "view_log"
      ],
      "createdBy": {
        "userpicUrl": null,
        "id": "1",
        "displayName": "Yuji Takayama"
      },
      "user": {
        "userpicUrl": null,
        "id": "1",
        "displayName": "Yuji Takayama"
      },
      "blog": {
        "id": "2"
      },
      "id": "3",
      "createdDate": "2015-03-21T19:37:53+09:00"
    }
  ]
}

Retrieve a list of permissions by site
GET/sites/{site_id}/permissions{?limit,offset,sortBy,sortOrder,fields,dateField,dateFrom,dateTo}

Retrieve a list of permissions by site.

Authentication required

  • Permissions
    • Administer
    • Website Administrator for websites
    • Blog Administrator for blog

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/permissions?limit=&offset=&sortBy=&sortOrder=&fields=&dateField=&dateFrom=&dateTo=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

limit
number (optional) Default: 25 

Maximum number of permissions to retrieve.

offset
number (optional) Default: 0 

0-indexed offset.

sortBy
string (optional) Default: bog_id 

The field name for sort. You can specify one of following values

  • id
  • blog_id
  • author_id
  • created_by
  • created_on

sortOrder
string (optional) Default: ascend 
descend
(default) Return permissions in descending order.
ascend
Return permissions in ascending order.
fields
string (optional) 

The field list to retrieve as part of the Permissions resource. That list should be separated by comma. If this parameter is not specified, All fields will be returned.

dateField
string (optional) Default: created_on 

Specifies the field name to be used as a date field for filtering. (new in v3)

dateFrom
string (optional) 

The start date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

dateTo
string (optional) 

The end date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

Request
HideShow
Headers
X-MT-Authorization: MTAuth accessToken=<Token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults": 1,
  "items": [
    {
      "roles": [
        {
          "name": "Website Administrator",
          "id": 1
        }
      ],
      "permissions": [
        "administer",
        "administer_blog",
        "administer_website",
        "comment",
        "create_blog",
        "create_post",
        "create_website",
        "edit_all_posts",
        "edit_assets",
        "edit_categories",
        "edit_config",
        "edit_notifications",
        "edit_tags",
        "edit_templates",
        "manage_feedback",
        "manage_member_blogs",
        "manage_pages",
        "manage_plugins",
        "manage_themes",
        "manage_users",
        "publish_post",
        "rebuild",
        "save_image_defaults",
        "send_notifications",
        "set_publish_paths",
        "upload",
        "view_blog_log",
        "view_log"
      ],
      "createdBy": {
        "userpicUrl": null,
        "id": "1",
        "displayName": "Yuji Takayama"
      },
      "user": {
        "userpicUrl": null,
        "id": "1",
        "displayName": "Yuji Takayama"
      },
      "blog": {
        "id": "2"
      },
      "id": "3",
      "createdDate": "2015-03-21T19:37:53+09:00"
    }
  ]
}

Retrieve a list of permissions by role
GET/roles/{role_id}/permissions{?limit,offset,sortBy,sortOrder,fields,blogIds,dateField,dateFrom,dateTo}

Retrieve a list of permissions by role. Only system administrator can call this endpoint.

Authentication required

  • Permissions
    • Administer

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/roles/role_id/permissions?limit=&offset=&sortBy=&sortOrder=&fields=&blogIds=&dateField=&dateFrom=&dateTo=
URI Parameters
HideShow
role_id
number (required) 

The role ID.

limit
number (optional) Default: 25 

Maximum number of permissions to retrieve.

offset
number (optional) Default: 0 

0-indexed offset.

sortBy
string (optional) Default: bog_id 

The field name for sort. You can specify one of following values

  • id
  • blog_id
  • author_id
  • created_by
  • created_on

sortOrder
string (optional) Default: ascend 
descend
(default) Return permissions in descending order.
ascend
Return permissions in ascending order.
fields
string (optional) 

The field list to retrieve as part of the Permissions resource. That list should be separated by comma. If this parameter is not specified, All fields will be returned.

blogIds
number (optional) 

The comma-separated blog id list that to be included in the result.

dateField
string (optional) Default: created_on 

Specifies the field name to be used as a date field for filtering. (new in v3)

dateFrom
string (optional) 

The start date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

dateTo
string (optional) 

The end date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

Request
HideShow
Headers
X-MT-Authorization: MTAuth accessToken=<Token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults": 1,
  "items": [
    {
      "roles": [
        {
          "name": "Website Administrator",
          "id": 1
        }
      ],
      "permissions": [
        "administer",
        "administer_blog",
        "administer_website",
        "comment",
        "create_blog",
        "create_post",
        "create_website",
        "edit_all_posts",
        "edit_assets",
        "edit_categories",
        "edit_config",
        "edit_notifications",
        "edit_tags",
        "edit_templates",
        "manage_feedback",
        "manage_member_blogs",
        "manage_pages",
        "manage_plugins",
        "manage_themes",
        "manage_users",
        "publish_post",
        "rebuild",
        "save_image_defaults",
        "send_notifications",
        "set_publish_paths",
        "upload",
        "view_blog_log",
        "view_log"
      ],
      "createdBy": {
        "userpicUrl": null,
        "id": "1",
        "displayName": "Yuji Takayama"
      },
      "user": {
        "userpicUrl": null,
        "id": "1",
        "displayName": "Yuji Takayama"
      },
      "blog": {
        "id": "2"
      },
      "id": "3",
      "createdDate": "2015-03-21T19:37:53+09:00"
    }
  ]
}

Grant permission

Grant permissions to site.
POST/sites/{site_id}/permissions/grant

Authentication required

You should have grant_administer_role or grant_role_for_blog (Need grant_administer_role when granting role having administer_blog).

Post form data is follows

  • role_id (required, number) - The role ID.

  • user_id (required, number) - The user ID.

Example URI

POST http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/permissions/grant
URI Parameters
HideShow
site_id
number (required) 

The site ID.

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
X-MT-Authorization: MTAuth accessToken=<Token>
Body
role_id=<role_id>&user_id=<user_id>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": "success"
}

Grant permissions to user.
POST/users/{user_id}/permissions/grant

Authentication required

You should have grant_administer_role or grant_role_for_blog (Need grant_administer_role when granting role having administer_blog).

Post form data is follows

  • site_id (required, number) - The site ID.

  • role_id (required, number) - The role ID.

Example URI

POST http://your-host/path-to-mt/mt-data-api.cgi/v3/users/user_id/permissions/grant
URI Parameters
HideShow
user_id
number (required) 

The user ID.

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
X-MT-Authorization: MTAuth accessToken=<Token>
Body
role_id=<role_id>&site_id=<site_id>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": "success"
}

Revoke permission

Revoke permissions from site.
POST/sites/{site_id}/permissions/revoke

Authentication required

  • You should have revoke_role(Need revoke_administer_role when granting role having administer_blog ).

Post form data is follows

  • user_id (required, number) - The user ID.

  • role_id (required, number) - The role ID.

Example URI

POST http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/permissions/revoke
URI Parameters
HideShow
site_id
number (required) 

The site ID.

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
X-MT-Authorization: MTAuth accessToken=<Token>
Body
role_id=<role_id>&user_id=<user_id>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": "success"
}

Revoke permissions from user.
POST/users/{user_id}/permissions/revoke

Authentication required

  • You should have revoke_role(Need revoke_administer_role when granting role having administer_blog ).

Post form data is follows

  • site_id (required, number) - The site ID.

  • role_id (required, number) - The role ID.

Example URI

POST http://your-host/path-to-mt/mt-data-api.cgi/v3/users/user_id/permissions/revoke
URI Parameters
HideShow
user_id
number (required) 

The user ID.

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
X-MT-Authorization: MTAuth accessToken=<Token>
Body
role_id=<role_id>&site_id=<site_id>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": "success"
}

Sites

This is the Sites resource.

Property Name Type Data Type Database Column Private Read Only Description Version
allowCommenterRegist value boolean mt_blog.blog_allow_commenter_regist Y
true
Allow visitors to register as members of this website using one of the Authentication Methods selected below.
false
Not allowed.
 v2
allowCommentHtml value boolean mt_blog.blog_allow_comment_html Y
true
Allow commenters to include a limited set of HTML tags in their comments.
false
All HTML will be stripped out.
 v2
allowComments value boolean mt_blog.blog_allow_reg_comments
mt_blog.blog_allow_unreg_comments		 Y
true
Accept comments.
false
Do not accept comments.
 v2
allowCommentsDefault value boolean mt_blog.blog_allow_comments_default Y The state of the comment acceptance of default in this site.
true
Comments are accepted.
false
Comments are not accepted.
 v2
allowPings value boolean mt_blog.blog_allow_pings Y -
true
Accept TrackBacks from any source.
false
Do not accept.
 v2
allowPingsDefault value boolean mt_blog.blog_allow_pings_default Y The state of the comment acceptance of default in this site. Available value is follows.
true
Trackbacks are accepted.
false
Trackbacks are not accepted.
 v2
allowToChangeAtUpload value boolean mt_blog.blog_allow_to_change_at_upload Y
true
Allow user to change the upload destination when upload a file.
false
Not allowed.
 v3.01
allowUnregComments value boolean mt_blog.blog_allow_unreg_comments Y
true
Allow comments from anonymous or unauthenticated users.
false
Not allowed.
 v2
archivePath value string mt_blog.blog_archive_path Y The archive path for this site. This property only accepts absolute path. v2
archiveTypePreferred value string mt_blog.blog_archive_type_preferred Y The preferred archive type for this site. v2
archiveUrl value string mt_blog.blog_archive_url The archive url of this site. [Update in v2] This property was changed to updatable. v1
autodiscoverLinks value boolean mt_blog.blog_autodiscovery_links Y
true
Enable External TrackBack Auto-Discovery.
false
Disable.
 v2
autolinkUrls value boolean mt_blog.blog_autolink_urls Y
true
Transform URLs in comment text into HTML links
false
Do not transform.
 v2
autoRenameNonAscii value boolean mt_blog_meta.auto_rename_non_ascii Y
true
Uploded file name will be automatically changed to randam filename if uploaded filename contains non-ascii character.
false
File name is not changed.
 v3.01
basenameLimit value number mt_blog.blog_basename_limit Y The maximum length of basename. v2
ccLicenseImage value string mt_blog.blog_cc_license - Y The URL for the Creative Commons License image for this site. v2
ccLicenseUrl value string mt_blog.blog_cc_license - Y The URL for the Creative Commons License url for this site. v2
class value string mt_blog.blog_class Y The object class for this site. v1
commenterAuthenticators ARRAY string mt_blog_meta.commenter_authenticators Y Array of commenter authenticators for this site. v2
convertParasComments value string mt_blog.blog_convert_paras_comments Y The text formatting of this site’s comment. v2
contentCss value string mt_blog.blog_content_css Y The CSS applying to WYSIWYG editor of this site. v2
convertParas value string mt_blog.blog_convert_paras Y The default text formatting in this site. Available value in default is follows.
0
The default text formatting is ‘None’
default
The default text formatting is ‘Convert Line Breaks’
markdown
The default text formatting is ‘Markdown’
markdown_with_smartypants
The default text formatting is ‘Markdown With SmartyPants’
richtext
The default text formatting is ‘Rich Text’
textile_2
The default text formatting is ‘Textile 2’
 v2
createdBy Object - Y The created user of this website. v2
createdBy.id value number mt_blog.blog_created_by Y Y The ID of created user. v2
createdBy.displayName value string Y The display name of created user. v2
createdBy.userpicUrl value string Y The URL of created user’s userpic. The userpic will be made by UserpicThumbnailSize and UserpicAllowRect settings. If user does not set own userpic, will be returned empty string. v2
createdDate value iso 8601 datetime mt_blog.blog_created_on Y The created time for this website. v2
customDynamicTemplates value string mt_blog.blog_custom_dynamic_templates Y Publishing profile for this site. Available value is follows.
none
Immediately publish all index templates and archive templates statically.
all
Publish all index templates and archive templates dynamically.
archives
Publish all archive templates dynamically. Immediately publish all index templates statically.
async_all
All index templates and archive templates published statically via Publish Que.
async_partial
mmediately publish Main Index template, Page archives statically. Use Publish Queue to publish all other index templates and archive templates statically.
 v2
daysOrPosts value string mt_blog.blog_days_on_index
mt_blog.blog_entries_on_index		 Y The type of listing default. Available value is follows.
days
Listing entries that written in the past N days. N is a value of listOnIndex.
posts
Listing most recent N entries. N is a value of listOnIndex.
 v2
dateLanguage value string mt_blog.blog_date_language - - The date locale settings for this site. Available valus is follow.
cz
Czech
dk
Danish
nl
Dutch
en
English
et
Estonian
fr
French
de
German
is
Icelandic
it
Italian
ja
Japanese
no
Norwegian
pl
Polish
pt
Portuguese
sk
Slovak
si
Slovenian
es
Spanish
fi
Suomi
se
Swedish
 v2
description value string mt_blog.blog_description The description of this site. [Update in v2] This property was changed to updatable. v1
dynamicCache value boolean Y Cannot set this property when dynamic templates does not exist.
true
Dynamic cache for dynamic publishing is enabled.
false
Dynamic cache for dynamic publishing is disabled.
 v2
dynamicConditional value boolean Y Cannot set this property when dynamic templates does not exist.
true
Dynamic conditional retrieval of dynamic publishing is enabled.
false
Dynamic conditional retrieval of dynamic publishing is disabled.
 v2
entryCustomPrefs ARRAY string Y Y Default displayed fields of this site’s entry. Available value is follows.
title
Title field
text
Body and extended field
category
Category list
excerpt
Excerpt field
keywords
Keyword field
tags
Tags field
feedback
Comment and trackback setting field
assets
Entry assets list
customfield_<basename>
Each custom Fields
 v2
emailNewComments value number mt_blog.blog_email_new_comments Y Email notification when posting comment to this site.
0
Off.
1
On.
2
Only when attension is required.
 v2
emailNewPings value number mt_blog.blog_email_new_pings Y "Email notification setting when accepting trackback to this site.
0
Off.
1
On.
2
Only when attention is required.
 v2
extraPath value string mt_blog_meta.blog_extra_path Y The raw data of extra path for default upload destination. If extra path is not configured, this value is a blank string. v3.01
fileExtension value string mt_blog.blog_file_extension Y The file extension for this site. v2
followAuthLinks value boolean mt_blog_meta.follow_auth_links Y
true
Do not add the ‘nofollow’ attribute when a comment is submitted by a trusted commenter.
false
Add the ‘nofollow’ attribute .
 v2
host value string mt_blog.blog_site_url - Y The host name of this site. v2
id value number mt_blog.blog_id Y The ID of this site. v1
includeCache value boolean mt_blog_meta:include_cache Y
true
Module cache is enabled.
false
Module cache is disabled.
 v2
includeSystem value string mt_blog_meta:include_system Y
‘’ (empty string)
Server Side Includes is disabled.
php
Server Side Include is enabled with PHP.
shtml
Server Side Include is enabled with Apache SSI.
asp
Server Side Include is enabled with ASP.
jsp
Server Side Include is enabled with JSP.
 v2
language value string mt_blog.blog_language The language for this site. Available value is follows.
de
German
en
English
es
Spanish
fl
French
nl
Dutch
ja
Japanese
 v2
internalAutodiscovery value boolean mt_blog.blog_internal_autodiscovery Y -
true
Enable Internal TrackBack Auto-Discovery
false
Disable.
 v2
junkFolderExpiry value number mt_blog.blog_junk_folder_expiry Y The period for deleting spam comments and trackbacks. v2
junkScoreThreshold value number mt_blog.blog_junk_score_threshold Y The spam score threshold of this site. v2
listOnIndex value number mt_blog.blog_days_on_index
mt_blog.blog_entries_on_index		 Y The number of entries shown in the list by default. v2
maxRevisionsEntry value number mt_blog_meta:max_revisions_entry Y The number of revisions per entries and pages in this site. v2
maxRevisionsTemplate value number mt_blog_meta.max_revisions_template Y The number of revisions per templates in this site. v2
moderateComments value number mt_blog.blog_moderate_unreg_comments Y
0
Anyone.
1
No one.
2
Trusted commenters only.
3
Any authenticated commenters.
 v2
moderatePings value boolean mt_blog.blog_moderate_pings Y
true
Hold all TrackBacks for approval before they are published.
false
Do not hold.
 v2
modifiedBy Object - Y The last modified user of this website. v2
modifiedBy.displayName value string Y The display name of last modified user. v2
modifiedBy.id value number mt_blog.blog_modified_by Y Y The ID of last modified user. v2
modifiedBy.userpicUrl value string Y The URL of last modified user’s userpic. The userpic will be made by UserpicThumbnailSize and UserpicAllowRect settings. If user does not set own userpic, will be returned empty string. v2
modifiedDate value iso 8601 datetime mt_blog.blog_modified_on Y The last modified time for this website. v2
name value string mt_blog.blog_name The name for this site. [Update in v2] This property was changed to updatable. v1
newCreatedUserRoles ARRAY Role - Y Assigned to users that are created in the future on this site. v2
newCreatedUserRole.id value number mt_role.role_id Y Y v2
newCreatedUserRole.name value string mt_role.role_name Y Y v2
nofollowUrls value boolean mt_blog_meta.nofollow_urls Y
true
All URLs in comments and TrackBacks will be assigned a ‘nofollow’ link relation.
false
Not assigned.
 v2
normalizeOrientation value boolean mt_blog_meta.normalize_orientation Y
true
Image orientation is normalized automatically when the image file contains orientation information.
false
Image orientation is will never normalized.
 v3.01
operationIfExists value number mt_blog_meta.operation_if_exists Y
1
The upload file will be changed to random file name automatically.
2
The existing file will be overwritten.
3
Upload will be canceled.
 v3.01
pageCustomPrefs ARRAY string Y Y Default displayed fields of this site’s page. Available value is follows.
title
Title field
text
Body and extended field
category
Category list
excerpt
Excerpt field
keywords
Keyword field
tags
Tags field
feedback
Comment and trackback setting field
assets
Page assets list
customfield_<basename>
Each custom Fields
 v2
parent Object - - - Y The parent website of this blog. If this object is Websites Resource, this object must be null. v2
parent.id value number mt_blog.blog_parent_id (mt_blog.blog_id) - Y The ID of parent website. v2
parent.name value string mt_blog.blog_name - Y The name of parent website. v2
publishEmptyArchive value boolean mt_blog_meta:publish_empty_archive
true
Category archive without entries is published.
false
Category archive without entries is not published.
 v2
pingGoogle value boolean mt_blog.blog_ping_google Y
true
Enable sending update ping to Google.
false
Disabled sending update ping to Google.
 v2
pingWeblogs value boolean mt_blog.blog_ping_weblogs Y
true
Enable sending update ping to weblogs.com.
false
Disabled sending update ping to weblogs.com.
 v2
pingOthers value string mt_blog.blog_ping_others Y - Array of update ping services. v2
relativeUrl value string mt_blog.blog_site_url - Y The relative site url of this site. v2
requireCommentEmails value boolean mt_blog.blog_require_comment_emails Y
true
Require name and E-mail Address for Anonymous Comments.
false
Do not require.
 v2
sanitizeSpec value string mt_blog.blog_santize_spec Y The limit html tags of this site’s comment. “0” is default. v2
serverOffset value number mt_blog.blog_server_offset The server offset for this site. v2
sitePath value string mt_blog.blog_site_path Y The site path for this site. This property only accepts absolute path. v2
siteSubdomain value string mt_blog.blog_site_url Y (Write Only) The subdomain for this site. This is write-only property. v2
smartReplace value number mt_blog.blog_nwc_smart_replace Y The punctuation replacement of this site.
0
No substitution.
1
Character entities.
2
ASCII equivalents.
 v2
sortOrderPosts value string mt_blog.blog_sort_order_posts Y The default sorting direction for the entry listing. Available value is follows.
ascend>/dt>Ascengin order.
descend
Descending order
 v2
sortOrderComments value string mt_blog.blog_sort_order_comments Y The comment order of this site. Available value is follows.
“ascend”
Ascending order
Descending order
 v2
smartReplaceFields ARRAY string mt_blog.blog_nwc_replace_field Y Replace fields of this site. v2
statusDefault value string mt_blog.blog_status_default Y The default entry status in this site. Available value is follows.
Pubish
The default status is ‘Published’
Draft
The default status is ‘Unpublished’
 v2
themeId value string mt_blog.blog_theme_id Y The theme ID for this site. v2
timezone value number mt_blog.mt_server_offset - Y The timezone of this site. v2
updatable value boolean Y
true
Current user can update this website.
false
Current user cannot update this website.
 v2
uploadDestination Object - - - Y The default configuration for upload destination of this site. v3.01
uploadDestination.path value string mt_blog_meta.blog_upload_destination Y The full path for default upload destination. The value begin with site path and contains extra path if extra_path configured. If default upload destination is not configured, this value is just a same as site_path. v3.01
uploadDestination.raw value string mt_blog_meta.blog_upload_destination Y The raw data of default upload destination. If default upload destination is not configured, this value is a blank string. v3.01
url value string mt_blog.blog_site_url The site url of this site. [Update in v2] This property was changed to updatable. v1
useCommentConfirmation value boolean mt_blog.blog_use_comment_confirmation Y
true
Each commenter’s browser will be redirected to a comment confirmation page after their comment is accepted.
false
Will not.
 v2
useRevision value boolean mt_blog.blog_use_revision Y
true
Revision history is enabled.
false
Revision history is disabled.
 v2
wordsInExcerpt value number mt_blog.blog_words_in_excerpt Y The default length for excerpt. v2

{ “serverOffset” : “9”, “themeId” : “rainier”, “statusDefault” : “Publish”, “autodiscoverLinks” : false, “useRevision” : true, “relativeUrl” : “/”, “entryCustomPrefs” : [ “title”, “body”, “category”, “tags”, “feedback”, “publishing”, “assets” ], “archivePath” : “/path/to/archive_root”, “useCommentConfirmation” : true, “url” : "http://example.com/", “smartReplaceFields” : [ “title”, “text”, “text_more”, “keywords”, “excerpt”, “tags” ], “modifiedBy” : { “userpicUrl” : null, “id” : “1”, “displayName” : “Yuji Takayama” }, “operationIfExists” : “2”, “timezone” : “+09:00”, “daysOrPosts” : “posts”, “sortOrderPosts” : “descend”, “name” : “First Website”, “convertParas” : “richtext”, “description” : “”, “autoRenameNonAscii” : true, “includeSystem” : “”, “archiveUrl” : "http://example.com/archives/", “allowCommentHtml” : true, “fileExtension” : “html”, “smartReplace” : 0, “junkFolderExpiry” : “14”, “publishEmptyArchive” : false, “dateLanguage” : “ja”, “listOnIndex” : “10”, “pingWeblogs” : false, “extraPath” : “uploads”, “normalizeOrientation” : false, “emailNewComments” : “1”, “language” : “ja”, “autolinkUrls” : true, “sanitizeSpec” : “0”, “customFields” : [], “emailNewPings” : “1”, “nofollowUrls” : true, “createdBy” : { “userpicUrl” : null, “id” : “1”, “displayName” : “Yuji Takayama” }, “pingGoogle” : false, “convertParasComments” : “1”, “sitePath” : “/path/to/site_path”, “id” : “1”, “parent” : null, “archiveTypePreferred” : “Individual”, “contentCss” : “{{theme_static}}css/editor.css”, “junkScoreThreshold” : “0”, “internalAutodiscovery” : false, “createdDate” : “2016-01-21T11:18:38+09:00”, “class” : “website”, “moderateComments” : “2”, “allowCommentsDefault” : true, “includeCache” : false, “allowCommenterRegist” : true, “allowToChangeAtUpload” : false, “uploadDestination” : { “path” : “/path/to/upload/dest”, “raw” : “%s/%y/%m” }, “maxRevisionsEntry” : “20”, “updatable” : true, “requireCommentEmails” : false, “ccLicenseImage” : “”, “allowComments” : true, “allowPingsDefault” : false, “pingOthers” : [], “basenameLimit” : “100”, “dynamicCache” : false, “modifiedDate” : “2016-01-21T11:30:03+09:00”, “allowPings” : false, “pageCustomPrefs” : [ “title”, “body”, “category”, “tags”, “feedback”, “publishing”, “assets” ], “dynamicConditional” : false, “commenterAuthenticators” : [ “MovableType” ], “host” : "example.com", “ccLicenseUrl” : “”, “newCreatedUserRoles” : [], “wordsInExcerpt” : “40”, “sortOrderComments” : “ascend”, “followAuthLinks” : true, “allowUnregComments” : false, “maxRevisionsTemplate” : “20”, “moderatePings” : true, “customDynamicTemplates” : “none” }

Sites

Retrieve a list of sites by user
GET/users/{user_id}/sites{?limit,offset,sortBy,sortOrder,fields,searchFields,search,includeIds,excludeIds,dateField,dateFrom,dateTo}

Retrieve a list of sites by user. The list includes only the site for which the user has any permissions.

Authentication required.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to retrieve the list of sites.
404 Not Found User not found.

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/users/user_id/sites?limit=&offset=&sortBy=&sortOrder=&fields=&searchFields=&search=&includeIds=&excludeIds=&dateField=&dateFrom=&dateTo=
URI Parameters
HideShow
user_id
number or 'me' (required) 

The user ID or the word ‘me’.

search
string (optional) 

Search query.

searchFields
string (optional) Default: name 

Only ‘name’ is available.

limit
number (optional) Default: 25 

Maximum number of sites to retrieve.

offset
number (optional) Default: 0 

0-indexed offset.

sortBy
string (optional) Default: name 

Only ‘name’ is available

sortOrder
string (optional) Default: descend 
descend
(default) Return sites in descending order.
ascend
Return sites in ascending order.
fields
string (optional) 

The field list to retrieve as part of the Sites resource. That list should be separated by comma. If this parameter is not specified, All fields will be returned.

includeIds
string (optional) 

The comma separated ID list of sites to include to result.

excludeIds
string (optional) 

The comma separated ID list of sites to exclude from result.

dateField
string (optional) Default: created_on 

Specifies the field name to be used as a date field for filtering. (new in v3)

dateFrom
string (optional) 

The start date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

dateTo
string (optional) 

The end date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults": 1,
  "items": [
    {
      "serverOffset": "9",
      "themeId": "rainier",
      "statusDefault": "Publish",
      "autodiscoverLinks": false,
      "useRevision": true,
      "relativeUrl": "/",
      "entryCustomPrefs": [
        "title",
        "body",
        "category",
        "tags",
        "feedback",
        "publishing",
        "assets"
      ],
      "archivePath": "/path/to/archive_root",
      "useCommentConfirmation": true,
      "url": "http://example.com/",
      "smartReplaceFields": [
        "title",
        "text",
        "text_more",
        "keywords",
        "excerpt",
        "tags"
      ],
      "modifiedBy": {
        "userpicUrl": null,
        "id": "1",
        "displayName": "Yuji Takayama"
      },
      "operationIfExists": "2",
      "timezone": "+09:00",
      "daysOrPosts": "posts",
      "sortOrderPosts": "descend",
      "name": "First Website",
      "convertParas": "richtext",
      "description": "",
      "autoRenameNonAscii": true,
      "includeSystem": "",
      "archiveUrl": "http://example.com/archives/",
      "allowCommentHtml": true,
      "fileExtension": "html",
      "smartReplace": 0,
      "junkFolderExpiry": "14",
      "publishEmptyArchive": false,
      "dateLanguage": "ja",
      "listOnIndex": "10",
      "pingWeblogs": false,
      "extraPath": "uploads",
      "normalizeOrientation": false,
      "emailNewComments": "1",
      "language": "ja",
      "autolinkUrls": true,
      "sanitizeSpec": "0",
      "customFields": [],
      "emailNewPings": "1",
      "nofollowUrls": true,
      "createdBy": {
        "userpicUrl": null,
        "id": "1",
        "displayName": "Yuji Takayama"
      },
      "pingGoogle": false,
      "convertParasComments": "1",
      "sitePath": "/path/to/site_path",
      "id": "1",
      "parent": null,
      "archiveTypePreferred": "Individual",
      "contentCss": "{{theme_static}}css/editor.css",
      "junkScoreThreshold": "0",
      "internalAutodiscovery": false,
      "createdDate": "2016-01-21T11:18:38+09:00",
      "class": "website",
      "moderateComments": "2",
      "allowCommentsDefault": true,
      "includeCache": false,
      "allowCommenterRegist": true,
      "allowToChangeAtUpload": false,
      "uploadDestination": {
        "path": "/path/to/upload/dest",
        "raw": "%s/%y/%m"
      },
      "maxRevisionsEntry": "20",
      "updatable": true,
      "requireCommentEmails": false,
      "ccLicenseImage": "",
      "allowComments": true,
      "allowPingsDefault": false,
      "pingOthers": [],
      "basenameLimit": "100",
      "dynamicCache": false,
      "modifiedDate": "2016-01-21T11:30:03+09:00",
      "allowPings": false,
      "pageCustomPrefs": [
        "title",
        "body",
        "category",
        "tags",
        "feedback",
        "publishing",
        "assets"
      ],
      "dynamicConditional": false,
      "commenterAuthenticators": [
        "MovableType"
      ],
      "host": "example.com",
      "ccLicenseUrl": "",
      "newCreatedUserRoles": [],
      "wordsInExcerpt": "40",
      "sortOrderComments": "ascend",
      "followAuthLinks": true,
      "allowUnregComments": false,
      "maxRevisionsTemplate": "20",
      "moderatePings": true,
      "customDynamicTemplates": "none"
    }
  ]
}

Retrieve a list of sites
GET/sites{?limit,offset,sortBy,sortOrder,fields,searchFields,search,includeIds,excludeIds,dateField,dateFrom,dateTo}

Retrieve a list of sites.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to retrieve the list of sites.

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites?limit=&offset=&sortBy=&sortOrder=&fields=&searchFields=&search=&includeIds=&excludeIds=&dateField=&dateFrom=&dateTo=
URI Parameters
HideShow
search
string (optional) 

Search query.

searchFields
string (optional) Default: name 

Only ‘name’ is available.

limit
number (optional) Default: 25 

Maximum number of sites to retrieve.

offset
number (optional) Default: 0 

0-indexed offset.

sortBy
string (optional) Default: name 

Only ‘name’ is available

sortOrder
string (optional) Default: descend 
descend
(default) Return sites in descending order.
ascend
Return sites in ascending order.
fields
string (optional) 

The field list to retrieve as part of the Sites resource. That list should be separated by comma. If this parameter is not specified, All fields will be returned.

includeIds
string (optional) 

The comma separated ID list of sites to include to result.

excludeIds
string (optional) 

The comma separated ID list of sites to exclude from result.

dateField
string (optional) Default: created_on 

Specifies the field name to be used as a date field for filtering. (new in v3)

dateFrom
string (optional) 

The start date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

dateTo
string (optional) 

The end date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults": 1,
  "items": [
    {
      "serverOffset": "9",
      "themeId": "rainier",
      "statusDefault": "Publish",
      "autodiscoverLinks": false,
      "useRevision": true,
      "relativeUrl": "/",
      "entryCustomPrefs": [
        "title",
        "body",
        "category",
        "tags",
        "feedback",
        "publishing",
        "assets"
      ],
      "archivePath": "/path/to/archive_root",
      "useCommentConfirmation": true,
      "url": "http://example.com/",
      "smartReplaceFields": [
        "title",
        "text",
        "text_more",
        "keywords",
        "excerpt",
        "tags"
      ],
      "modifiedBy": {
        "userpicUrl": null,
        "id": "1",
        "displayName": "Yuji Takayama"
      },
      "operationIfExists": "2",
      "timezone": "+09:00",
      "daysOrPosts": "posts",
      "sortOrderPosts": "descend",
      "name": "First Website",
      "convertParas": "richtext",
      "description": "",
      "autoRenameNonAscii": true,
      "includeSystem": "",
      "archiveUrl": "http://example.com/archives/",
      "allowCommentHtml": true,
      "fileExtension": "html",
      "smartReplace": 0,
      "junkFolderExpiry": "14",
      "publishEmptyArchive": false,
      "dateLanguage": "ja",
      "listOnIndex": "10",
      "pingWeblogs": false,
      "extraPath": "uploads",
      "normalizeOrientation": false,
      "emailNewComments": "1",
      "language": "ja",
      "autolinkUrls": true,
      "sanitizeSpec": "0",
      "customFields": [],
      "emailNewPings": "1",
      "nofollowUrls": true,
      "createdBy": {
        "userpicUrl": null,
        "id": "1",
        "displayName": "Yuji Takayama"
      },
      "pingGoogle": false,
      "convertParasComments": "1",
      "sitePath": "/path/to/site_path",
      "id": "1",
      "parent": null,
      "archiveTypePreferred": "Individual",
      "contentCss": "{{theme_static}}css/editor.css",
      "junkScoreThreshold": "0",
      "internalAutodiscovery": false,
      "createdDate": "2016-01-21T11:18:38+09:00",
      "class": "website",
      "moderateComments": "2",
      "allowCommentsDefault": true,
      "includeCache": false,
      "allowCommenterRegist": true,
      "allowToChangeAtUpload": false,
      "uploadDestination": {
        "path": "/path/to/upload/dest",
        "raw": "%s/%y/%m"
      },
      "maxRevisionsEntry": "20",
      "updatable": true,
      "requireCommentEmails": false,
      "ccLicenseImage": "",
      "allowComments": true,
      "allowPingsDefault": false,
      "pingOthers": [],
      "basenameLimit": "100",
      "dynamicCache": false,
      "modifiedDate": "2016-01-21T11:30:03+09:00",
      "allowPings": false,
      "pageCustomPrefs": [
        "title",
        "body",
        "category",
        "tags",
        "feedback",
        "publishing",
        "assets"
      ],
      "dynamicConditional": false,
      "commenterAuthenticators": [
        "MovableType"
      ],
      "host": "example.com",
      "ccLicenseUrl": "",
      "newCreatedUserRoles": [],
      "wordsInExcerpt": "40",
      "sortOrderComments": "ascend",
      "followAuthLinks": true,
      "allowUnregComments": false,
      "maxRevisionsTemplate": "20",
      "moderatePings": true,
      "customDynamicTemplates": "none"
    }
  ]
}

Retrieve a list of sites by parent site
GET/sites/{site_id}/children{?limit,offset,sortBy,sortOrder,fields,searchFields,search,includeIds,excludeIds,dateField,dateFrom,dateTo}

Retrieve a list of sites by parent site

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to retrieve the list of sites.
404 Not Found Site not found.

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/children?limit=&offset=&sortBy=&sortOrder=&fields=&searchFields=&search=&includeIds=&excludeIds=&dateField=&dateFrom=&dateTo=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

search
string (optional) 

Search query.

searchFields
string (optional) Default: name 

Only ‘name’ is available.

limit
number (optional) Default: 25 

Maximum number of sites to retrieve.

offset
number (optional) Default: 0 

0-indexed offset.

sortBy
string (optional) Default: name 

Only ‘name’ is available

sortOrder
string (optional) Default: descend 
descend
(default) Return sites in descending order.
ascend
Return sites in ascending order.
fields
string (optional) 

The field list to retrieve as part of the Sites resource. That list should be separated by comma. If this parameter is not specified, All fields will be returned.

includeIds
string (optional) 

The comma separated ID list of sites to include to result.

excludeIds
string (optional) 

The comma separated ID list of sites to exclude from result.

dateField
string (optional) Default: created_on 

Specifies the field name to be used as a date field for filtering. (new in v3)

dateFrom
string (optional) 

The start date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

dateTo
string (optional) 

The end date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults": 1,
  "items": [
    {
      "serverOffset": "9",
      "themeId": "rainier",
      "statusDefault": "Publish",
      "autodiscoverLinks": false,
      "useRevision": true,
      "relativeUrl": "/",
      "entryCustomPrefs": [
        "title",
        "text",
        "category",
        "excerpt",
        "keywords",
        "tags",
        "feedback",
        "assets",
        "customfield_license_fee",
        "customfield_foo"
      ],
      "archivePath": "/path/to/document_root/",
      "useCommentConfirmation": true,
      "url": "http://example.com/",
      "smartReplaceFields": [
        "title",
        "text",
        "text_more",
        "keywords",
        "excerpt",
        "tags"
      ],
      "modifiedBy": {
        "userpicUrl": null,
        "id": "1",
        "displayName": "Yuji Takayama"
      },
      "timezone": "+09:00",
      "daysOrPosts": "posts",
      "sortOrderPosts": "descend",
      "name": "Six Apart Shop",
      "convertParas": "richtext",
      "description": "",
      "includeSystem": "",
      "archiveUrl": "http://example.com",
      "allowCommentHtml": true,
      "fileExtension": "html",
      "smartReplace": "0",
      "junkFolderExpiry": "14",
      "publishEmptyArchive": false,
      "dateLanguage": "ja",
      "listOnIndex": "10",
      "pingWeblogs": true,
      "emailNewComments": "1",
      "language": "ja",
      "autolinkUrls": true,
      "sanitizeSpec": "0",
      "customFields": [],
      "emailNewPings": "1",
      "nofollowUrls": true,
      "createdBy": {
        "userpicUrl": null,
        "id": "1",
        "displayName": "Yuji Takayama"
      },
      "pingGoogle": true,
      "convertParasComments": "1",
      "sitePath": "/path/to/document_root/",
      "id": "2",
      "parent": {
        "id": "1",
        "name": "Parent Website"
      },
      "archiveTypePreferred": "Individual",
      "contentCss": "{{theme_static}}css/editor.css",
      "junkScoreThreshold": "0",
      "internalAutodiscovery": false,
      "createdDate": "2014-12-28T23:09:45+09:00",
      "class": "website",
      "moderateComments": "2",
      "allowCommentsDefault": true,
      "includeCache": false,
      "allowCommenterRegist": true,
      "maxRevisionsEntry": "20",
      "updatable": true,
      "requireCommentEmails": false,
      "ccLicenseImage": "https://i.creativecommons.org/l/by/4.0/88x31.png",
      "allowComments": true,
      "allowPingsDefault": false,
      "pingOthers": [],
      "dynamicCache": false,
      "basenameLimit": "100",
      "modifiedDate": "2015-03-12T12:16:24+09:00",
      "dynamicConditional": false,
      "pageCustomPrefs": [
        "title",
        "text",
        "excerpt",
        "keywords",
        "tags",
        "feedback",
        "assets"
      ],
      "allowPings": false,
      "commenterAuthenticators": [
        "MovableType"
      ],
      "host": "localhost",
      "ccLicenseUrl": "http://creativecommons.org/licenses/by/4.0/",
      "newCreatedUserRoles": [],
      "wordsInExcerpt": "40",
      "sortOrderComments": "ascend",
      "followAuthLinks": true,
      "allowUnregComments": false,
      "maxRevisionsTemplate": "20",
      "moderatePings": true,
      "customDynamicTemplates": "none"
    }
  ]
}

Create a new website
POST/sites

Create a new website.

Authentication required.

This method accepts PUT and POST with __method=PUT.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to create a new website.
404 Not Found Site not found.

Permissions

  • create_website

Request Body Parameters

Name Type Required Default Description
blog Object Yes Single Sites resource

Example URI

POST http://your-host/path-to-mt/mt-data-api.cgi/v3/sites
Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
X-MT-Authorization: MTAuth accessToken={Token}
Body
website={"url" : "http://example.com/", "name" : "New Website", "sitePath":"/path/to/document_root/"}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "serverOffset": "9",
  "themeId": "rainier",
  "statusDefault": "Publish",
  "autodiscoverLinks": false,
  "useRevision": true,
  "relativeUrl": "/",
  "entryCustomPrefs": [
    "title",
    "text",
    "category",
    "excerpt",
    "keywords",
    "tags",
    "feedback",
    "assets",
    "customfield_license_fee",
    "customfield_foo"
  ],
  "archivePath": "/path/to/document_root/",
  "useCommentConfirmation": true,
  "url": "http://example.com/",
  "smartReplaceFields": [
    "title",
    "text",
    "text_more",
    "keywords",
    "excerpt",
    "tags"
  ],
  "modifiedBy": {
    "userpicUrl": null,
    "id": "1",
    "displayName": "Yuji Takayama"
  },
  "timezone": "+09:00",
  "daysOrPosts": "posts",
  "sortOrderPosts": "descend",
  "name": "Six Apart Shop",
  "convertParas": "richtext",
  "description": "",
  "includeSystem": "",
  "archiveUrl": "http://example.com",
  "allowCommentHtml": true,
  "fileExtension": "html",
  "smartReplace": "0",
  "junkFolderExpiry": "14",
  "publishEmptyArchive": false,
  "dateLanguage": "ja",
  "listOnIndex": "10",
  "pingWeblogs": true,
  "emailNewComments": "1",
  "language": "ja",
  "autolinkUrls": true,
  "sanitizeSpec": "0",
  "customFields": [],
  "emailNewPings": "1",
  "nofollowUrls": true,
  "createdBy": {
    "userpicUrl": null,
    "id": "1",
    "displayName": "Yuji Takayama"
  },
  "pingGoogle": true,
  "convertParasComments": "1",
  "sitePath": "/path/to/document_root/",
  "id": "2",
  "parent": {
    "id": "1",
    "name": "Parent Website"
  },
  "archiveTypePreferred": "Individual",
  "contentCss": "{{theme_static}}css/editor.css",
  "junkScoreThreshold": "0",
  "internalAutodiscovery": false,
  "createdDate": "2014-12-28T23:09:45+09:00",
  "class": "website",
  "moderateComments": "2",
  "allowCommentsDefault": true,
  "includeCache": false,
  "allowCommenterRegist": true,
  "maxRevisionsEntry": "20",
  "updatable": true,
  "requireCommentEmails": false,
  "ccLicenseImage": "https://i.creativecommons.org/l/by/4.0/88x31.png",
  "allowComments": true,
  "allowPingsDefault": false,
  "pingOthers": [],
  "dynamicCache": false,
  "basenameLimit": "100",
  "modifiedDate": "2015-03-12T12:16:24+09:00",
  "dynamicConditional": false,
  "pageCustomPrefs": [
    "title",
    "text",
    "excerpt",
    "keywords",
    "tags",
    "feedback",
    "assets"
  ],
  "allowPings": false,
  "commenterAuthenticators": [
    "MovableType"
  ],
  "host": "localhost",
  "ccLicenseUrl": "http://creativecommons.org/licenses/by/4.0/",
  "newCreatedUserRoles": [],
  "wordsInExcerpt": "40",
  "sortOrderComments": "ascend",
  "followAuthLinks": true,
  "allowUnregComments": false,
  "maxRevisionsTemplate": "20",
  "moderatePings": true,
  "customDynamicTemplates": "none"
}

Create a new blog under the site
POST/sites/{site_id}

Create a new blog under the site.

Authentication required.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to create a new blog.
404 Not Found Site not found.

Permissions

  • create_blog

Request Body Parameters

Name Type Required Default Description
blog Object Yes Single Sites resource

Example URI

POST http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id
URI Parameters
HideShow
site_id
number (required) 

The site ID.

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
X-MT-Authorization: MTAuth accessToken={Token}
Body
blog={"name":"New Blog", "url":"blog", "sitePath":"blog"}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "serverOffset": "9",
  "themeId": "mt_community_forum",
  "statusDefault": "Publish",
  "autodiscoverLinks": false,
  "useRevision": true,
  "relativeUrl": "/communityforum/",
  "entryCustomPrefs": [
    "title",
    "body",
    "category",
    "tags",
    "feedback",
    "publishing",
    "assets"
  ],
  "archivePath": "/path/to/archive_root",
  "useCommentConfirmation": true,
  "url": "https://example.com/",
  "smartReplaceFields": [
    "title",
    "text",
    "text_more",
    "keywords",
    "excerpt",
    "tags"
  ],
  "operationIfExists": 1,
  "timezone": "+09:00",
  "daysOrPosts": "posts",
  "sortOrderPosts": "descend",
  "name": "CommunityForum",
  "convertParas": "richtext",
  "description": null,
  "autoRenameNonAscii": true,
  "includeSystem": null,
  "archiveUrl": "https://example.com/archives/",
  "allowCommentHtml": true,
  "fileExtension": "html",
  "smartReplace": 0,
  "junkFolderExpiry": "14",
  "publishEmptyArchive": false,
  "dateLanguage": "ja",
  "listOnIndex": "10",
  "pingWeblogs": false,
  "extraPath": "",
  "normalizeOrientation": true,
  "emailNewComments": "1",
  "language": "ja",
  "autolinkUrls": true,
  "sanitizeSpec": "0",
  "customFields": [],
  "emailNewPings": "1",
  "nofollowUrls": true,
  "createdBy": {
    "userpicUrl": null,
    "id": "1",
    "displayName": "Yuji Takayama"
  },
  "pingGoogle": false,
  "convertParasComments": "1",
  "sitePath": "/path/to/site_root",
  "id": "4",
  "parent": {
    "name": "First Website",
    "id": "1"
  },
  "archiveTypePreferred": "Individual",
  "contentCss": null,
  "junkScoreThreshold": "0",
  "internalAutodiscovery": false,
  "createdDate": "2016-02-09T16:20:24+09:00",
  "class": "blog",
  "moderateComments": "2",
  "allowCommentsDefault": true,
  "includeCache": false,
  "allowCommenterRegist": true,
  "allowToChangeAtUpload": true,
  "uploadDestination": {
    "path": "/path/to/upload/destination",
    "raw": ""
  },
  "maxRevisionsEntry": null,
  "updatable": true,
  "requireCommentEmails": false,
  "ccLicenseImage": "",
  "allowComments": true,
  "allowPingsDefault": true,
  "pingOthers": [],
  "basenameLimit": "100",
  "dynamicCache": false,
  "modifiedDate": "2016-02-09T16:20:24+09:00",
  "allowPings": false,
  "pageCustomPrefs": [
    "title",
    "body",
    "category",
    "tags",
    "feedback",
    "publishing",
    "assets"
  ],
  "dynamicConditional": false,
  "commenterAuthenticators": [
    "MovableType"
  ],
  "host": "example.com",
  "ccLicenseUrl": "",
  "newCreatedUserRoles": [],
  "wordsInExcerpt": "40",
  "sortOrderComments": "ascend",
  "followAuthLinks": true,
  "allowUnregComments": false,
  "maxRevisionsTemplate": null,
  "moderatePings": true,
  "customDynamicTemplates": "none"
}

Update an existing blog or website
PUT/sites/{site_id}

Update an existing blog or website.

Authentication required.

This method accepts PUT and POST with __method=PUT.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to update an existing blog or website.
404 Not Found Site not found.

Permissions

  • edit_blog_config

Request Body Parameters

Name Type Required Default Description
blog Object Yes Single Sites resource

Example URI

PUT http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id
URI Parameters
HideShow
site_id
number (required) 

The site ID.

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
X-MT-Authorization: MTAuth accessToken=<Token>
Body
website={"name" : "Our new Website"} or blog={"name" : "Our new Website"}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "serverOffset": "9",
  "themeId": "rainier",
  "statusDefault": "Publish",
  "autodiscoverLinks": false,
  "useRevision": true,
  "relativeUrl": "/",
  "entryCustomPrefs": [
    "title",
    "text",
    "category",
    "excerpt",
    "keywords",
    "tags",
    "feedback",
    "assets",
    "customfield_license_fee",
    "customfield_foo"
  ],
  "archivePath": "/path/to/document_root/",
  "useCommentConfirmation": true,
  "url": "http://example.com/",
  "smartReplaceFields": [
    "title",
    "text",
    "text_more",
    "keywords",
    "excerpt",
    "tags"
  ],
  "modifiedBy": {
    "userpicUrl": null,
    "id": "1",
    "displayName": "Yuji Takayama"
  },
  "timezone": "+09:00",
  "daysOrPosts": "posts",
  "sortOrderPosts": "descend",
  "name": "Six Apart Shop",
  "convertParas": "richtext",
  "description": "",
  "includeSystem": "",
  "archiveUrl": "http://example.com",
  "allowCommentHtml": true,
  "fileExtension": "html",
  "smartReplace": "0",
  "junkFolderExpiry": "14",
  "publishEmptyArchive": false,
  "dateLanguage": "ja",
  "listOnIndex": "10",
  "pingWeblogs": true,
  "emailNewComments": "1",
  "language": "ja",
  "autolinkUrls": true,
  "sanitizeSpec": "0",
  "customFields": [],
  "emailNewPings": "1",
  "nofollowUrls": true,
  "createdBy": {
    "userpicUrl": null,
    "id": "1",
    "displayName": "Yuji Takayama"
  },
  "pingGoogle": true,
  "convertParasComments": "1",
  "sitePath": "/path/to/document_root/",
  "id": "2",
  "parent": {
    "id": "1",
    "name": "Parent Website"
  },
  "archiveTypePreferred": "Individual",
  "contentCss": "{{theme_static}}css/editor.css",
  "junkScoreThreshold": "0",
  "internalAutodiscovery": false,
  "createdDate": "2014-12-28T23:09:45+09:00",
  "class": "website",
  "moderateComments": "2",
  "allowCommentsDefault": true,
  "includeCache": false,
  "allowCommenterRegist": true,
  "maxRevisionsEntry": "20",
  "updatable": true,
  "requireCommentEmails": false,
  "ccLicenseImage": "https://i.creativecommons.org/l/by/4.0/88x31.png",
  "allowComments": true,
  "allowPingsDefault": false,
  "pingOthers": [],
  "dynamicCache": false,
  "basenameLimit": "100",
  "modifiedDate": "2015-03-12T12:16:24+09:00",
  "dynamicConditional": false,
  "pageCustomPrefs": [
    "title",
    "text",
    "excerpt",
    "keywords",
    "tags",
    "feedback",
    "assets"
  ],
  "allowPings": false,
  "commenterAuthenticators": [
    "MovableType"
  ],
  "host": "localhost",
  "ccLicenseUrl": "http://creativecommons.org/licenses/by/4.0/",
  "newCreatedUserRoles": [],
  "wordsInExcerpt": "40",
  "sortOrderComments": "ascend",
  "followAuthLinks": true,
  "allowUnregComments": false,
  "maxRevisionsTemplate": "20",
  "moderatePings": true,
  "customDynamicTemplates": "none"
}

Delete an existing blog or website
DELETE/sites/{site_id}

Delete an existing blog or website.

Authentication required.

This method accepts DELETE and POST with __method=DELETE.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to delete an existing blog or website.
404 Not Found Site not found.

Permissions

  • delete_website (for website)

  • delete_blog (for blog)

Example URI

DELETE http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id
URI Parameters
HideShow
site_id
number (required) 

The site ID.

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
X-MT-Authorization: MTAuth accessToken={Token}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "serverOffset": "9",
  "themeId": "rainier",
  "statusDefault": "Publish",
  "autodiscoverLinks": false,
  "useRevision": true,
  "relativeUrl": "/",
  "entryCustomPrefs": [
    "title",
    "text",
    "category",
    "excerpt",
    "keywords",
    "tags",
    "feedback",
    "assets",
    "customfield_license_fee",
    "customfield_foo"
  ],
  "archivePath": "/path/to/document_root/",
  "useCommentConfirmation": true,
  "url": "http://example.com/",
  "smartReplaceFields": [
    "title",
    "text",
    "text_more",
    "keywords",
    "excerpt",
    "tags"
  ],
  "modifiedBy": {
    "userpicUrl": null,
    "id": "1",
    "displayName": "Yuji Takayama"
  },
  "timezone": "+09:00",
  "daysOrPosts": "posts",
  "sortOrderPosts": "descend",
  "name": "Six Apart Shop",
  "convertParas": "richtext",
  "description": "",
  "includeSystem": "",
  "archiveUrl": "http://example.com",
  "allowCommentHtml": true,
  "fileExtension": "html",
  "smartReplace": "0",
  "junkFolderExpiry": "14",
  "publishEmptyArchive": false,
  "dateLanguage": "ja",
  "listOnIndex": "10",
  "pingWeblogs": true,
  "emailNewComments": "1",
  "language": "ja",
  "autolinkUrls": true,
  "sanitizeSpec": "0",
  "customFields": [],
  "emailNewPings": "1",
  "nofollowUrls": true,
  "createdBy": {
    "userpicUrl": null,
    "id": "1",
    "displayName": "Yuji Takayama"
  },
  "pingGoogle": true,
  "convertParasComments": "1",
  "sitePath": "/path/to/document_root/",
  "id": "2",
  "parent": {
    "id": "1",
    "name": "Parent Website"
  },
  "archiveTypePreferred": "Individual",
  "contentCss": "{{theme_static}}css/editor.css",
  "junkScoreThreshold": "0",
  "internalAutodiscovery": false,
  "createdDate": "2014-12-28T23:09:45+09:00",
  "class": "website",
  "moderateComments": "2",
  "allowCommentsDefault": true,
  "includeCache": false,
  "allowCommenterRegist": true,
  "maxRevisionsEntry": "20",
  "updatable": true,
  "requireCommentEmails": false,
  "ccLicenseImage": "https://i.creativecommons.org/l/by/4.0/88x31.png",
  "allowComments": true,
  "allowPingsDefault": false,
  "pingOthers": [],
  "dynamicCache": false,
  "basenameLimit": "100",
  "modifiedDate": "2015-03-12T12:16:24+09:00",
  "dynamicConditional": false,
  "pageCustomPrefs": [
    "title",
    "text",
    "excerpt",
    "keywords",
    "tags",
    "feedback",
    "assets"
  ],
  "allowPings": false,
  "commenterAuthenticators": [
    "MovableType"
  ],
  "host": "localhost",
  "ccLicenseUrl": "http://creativecommons.org/licenses/by/4.0/",
  "newCreatedUserRoles": [],
  "wordsInExcerpt": "40",
  "sortOrderComments": "ascend",
  "followAuthLinks": true,
  "allowUnregComments": false,
  "maxRevisionsTemplate": "20",
  "moderatePings": true,
  "customDynamicTemplates": "none"
}

Retrieve a single website/blog by its ID
GET/sites/{site_id}{?fields}

Retrieve a single website/blog by its ID.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to get an existing Site.
404 Not Found Site not found.

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id?fields=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

fields
string (optional) 

The field list to retrieve as part of the Sites resource. That list should be separated by comma. If this parameter is not specified, All fields will be returned.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "serverOffset": "9",
  "themeId": "rainier",
  "statusDefault": "Publish",
  "autodiscoverLinks": false,
  "useRevision": true,
  "relativeUrl": "/",
  "entryCustomPrefs": [
    "title",
    "text",
    "category",
    "excerpt",
    "keywords",
    "tags",
    "feedback",
    "assets",
    "customfield_license_fee",
    "customfield_foo"
  ],
  "archivePath": "/path/to/document_root/",
  "useCommentConfirmation": true,
  "url": "http://example.com/",
  "smartReplaceFields": [
    "title",
    "text",
    "text_more",
    "keywords",
    "excerpt",
    "tags"
  ],
  "modifiedBy": {
    "userpicUrl": null,
    "id": "1",
    "displayName": "Yuji Takayama"
  },
  "timezone": "+09:00",
  "daysOrPosts": "posts",
  "sortOrderPosts": "descend",
  "name": "Six Apart Shop",
  "convertParas": "richtext",
  "description": "",
  "includeSystem": "",
  "archiveUrl": "http://example.com",
  "allowCommentHtml": true,
  "fileExtension": "html",
  "smartReplace": "0",
  "junkFolderExpiry": "14",
  "publishEmptyArchive": false,
  "dateLanguage": "ja",
  "listOnIndex": "10",
  "pingWeblogs": true,
  "emailNewComments": "1",
  "language": "ja",
  "autolinkUrls": true,
  "sanitizeSpec": "0",
  "customFields": [],
  "emailNewPings": "1",
  "nofollowUrls": true,
  "createdBy": {
    "userpicUrl": null,
    "id": "1",
    "displayName": "Yuji Takayama"
  },
  "pingGoogle": true,
  "convertParasComments": "1",
  "sitePath": "/path/to/document_root/",
  "id": "2",
  "parent": {
    "id": "1",
    "name": "Parent Website"
  },
  "archiveTypePreferred": "Individual",
  "contentCss": "{{theme_static}}css/editor.css",
  "junkScoreThreshold": "0",
  "internalAutodiscovery": false,
  "createdDate": "2014-12-28T23:09:45+09:00",
  "class": "website",
  "moderateComments": "2",
  "allowCommentsDefault": true,
  "includeCache": false,
  "allowCommenterRegist": true,
  "maxRevisionsEntry": "20",
  "updatable": true,
  "requireCommentEmails": false,
  "ccLicenseImage": "https://i.creativecommons.org/l/by/4.0/88x31.png",
  "allowComments": true,
  "allowPingsDefault": false,
  "pingOthers": [],
  "dynamicCache": false,
  "basenameLimit": "100",
  "modifiedDate": "2015-03-12T12:16:24+09:00",
  "dynamicConditional": false,
  "pageCustomPrefs": [
    "title",
    "text",
    "excerpt",
    "keywords",
    "tags",
    "feedback",
    "assets"
  ],
  "allowPings": false,
  "commenterAuthenticators": [
    "MovableType"
  ],
  "host": "localhost",
  "ccLicenseUrl": "http://creativecommons.org/licenses/by/4.0/",
  "newCreatedUserRoles": [],
  "wordsInExcerpt": "40",
  "sortOrderComments": "ascend",
  "followAuthLinks": true,
  "allowUnregComments": false,
  "maxRevisionsTemplate": "20",
  "moderatePings": true,
  "customDynamicTemplates": "none"
}

Stats

This is the PageStats(byPath) resource.

Property Name Type Data Type Database Column Private Read Only Description Version
path value String Y The relative path of the target. v1
pageviews value Number Y The number of pageviews for the path. This property exists only if request endpoint is “pageviewsForPath”. v1
visits value Number Y The number of visits for the path. This property exists only if request endpoint is “visitsForPath”. v1
archiveType value String mt_fileinfo.fileinfo_archive_type Y The archive type of the path. This property is null if the path is not managed by MT. v1
entry Object - Y This property is null if “archiveType” is not “Individual”. v1
entry.id value Number mt_entry.entry_id Y The ID of entry. v1
author Object - Y This property is null if “archiveType” is neither “Author” nor “Author-∗”. v1
author.id value Number mt_author.author_id Y The ID of author. v1
category Object - Y This property is null if “archiveType” is neither “Category” nor “Category-∗”. v1
category.id value Number mt_category.category_id Y The ID of category. v1

{ “totalResults”: 2, “items”: [ { “entry”: null, “pageviews”: “56”, “author”: null, “path”: “/”, “title”: “Your site”, “archiveType”: “index”, “category”: null, “startDate”: null }, { “entry”: { “id”: “1198” }, “pageviews”: “44”, “author”: null, “path”: “/2015/03/exapmle.html”, “title”: “Entry title is here”, “archiveType”: “Individual”, “category”: null, “startDate”: null }, ], “totals”: { “pageviews”: “329” } }

Also, This is the PageStats(byDate) resource.

Property Name Type Data Type Database Column Private Read Only Description Version
date value iso 8601 date Y The date of the target. The format is “YYYY-MM-DD”. v1
pageviews value Number Y The pageviews for the path. This property exists only if request endpoint is “pageviewsForDate”. v1
visits value Number Y The visits for the path. This property exists only if request endpoint is “visitsForDate”. v1

{ “totalResults”: 6, “items”: [ { “visits”: “1”, “date”: “2015-05-20” }, { “visits”: “1”, “date”: “2015-05-21” }, { “visits”: “2”, “date”: “2015-05-22” }, { “visits”: “1”, “date”: “2015-05-23” }, { “visits”: “1”, “date”: “2015-05-24” }, { “visits”: “4”, “date”: “2015-05-25” } ], “totals”: { “visits”: “10” } }

PageStats

Retrieve a list of visits data for each path
GET/sites/{site_id}/stats/path/visits{?startDate,endDate,limit,offset,path}

Retrieve a list of visits data for each path from the provider.

Authentication required.

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/stats/path/visits?startDate=&endDate=&limit=&offset=&path=
URI Parameters
HideShow
site_id
Number (required) 

The site ID.

startDate
String (required) 

This is an required parameter. Start date of data. The format is “YYYY-MM-DD”.

endDate
String (required) 

This is an required parameter. End date of data. The format is “YYYY-MM-DD”.

limit
Number (optional) 

This is an optional parameter. Maximum number of paths to retrieve. Default is 10.

offset
Number (optional) 

This is an optional parameter. 0-indexed offset. Default is 0.

path
String (optional) 

This is an optional parameter. The target path of data to retrieve. Default is the path of the current site.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults": 2,
  "items": [
    {
      "entry": null,
      "pageviews": "56",
      "author": null,
      "path": "/",
      "title": "Your site",
      "archiveType": "index",
      "category": null,
      "startDate": null
    },
    {
      "entry": {
        "id": "1198"
      },
      "pageviews": "44",
      "author": null,
      "path": "/2015/03/exapmle.html",
      "title": "Entry title is here",
      "archiveType": "Individual",
      "category": null,
      "startDate": null
    },
  ],
  "totals": {
    "pageviews": "329"
  }
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Unauthorized",
    "code": 401
  }
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Readied provider is not found",
    "code": "404"
  }
}

Retrieve a list of visits data for each date
GET/sites/{site_id}/stats/date/visits{?startDate,endDate,limit,offset,path}

Retrieve a list of visits data for each date from the provider.

Authentication required.

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/stats/date/visits?startDate=&endDate=&limit=&offset=&path=
URI Parameters
HideShow
site_id
Number (required) 

The site ID.

startDate
String (required) 

This is an required parameter. Start date of data. The format is “YYYY-MM-DD”.

endDate
String (required) 

This is an required parameter. End date of data. The format is “YYYY-MM-DD”.

limit
Number (optional) 

This is an optional parameter. Maximum number of paths to retrieve. Default is 10.

offset
Number (optional) 

This is an optional parameter. 0-indexed offset. Default is 0.

path
String (optional) 

This is an optional parameter. The target path of data to retrieve. Default is the path of the current site.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults": 6,
  "items": [
    {
      "visits": "1",
      "date": "2015-05-20"
    },
    {
      "visits": "1",
      "date": "2015-05-21"
    },
    {
      "visits": "2",
      "date": "2015-05-22"
    },
    {
      "visits": "1",
      "date": "2015-05-23"
    },
    {
      "visits": "1",
      "date": "2015-05-24"
    },
    {
      "visits": "4",
      "date": "2015-05-25"
    }
  ],
  "totals": {
    "visits": "10"
  }
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Unauthorized",
    "code": 401
  }
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Readied provider is not found",
    "code": "404"
  }
}

Retrieve a list of page view data for each path
GET/sites/{site_id}/stats/path/pageviews{?startDate,endDate,limit,offset,path,uniquePath}

Retrieve a list of page view data for each path from the provider.

Authentication required.

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/stats/path/pageviews?startDate=&endDate=&limit=&offset=&path=&uniquePath=
URI Parameters
HideShow
site_id
Number (required) 

The site ID.

startDate
String (required) 

This is an required parameter. Start date of data. The format is “YYYY-MM-DD”.

endDate
String (required) 

This is an required parameter. End date of data. The format is “YYYY-MM-DD”.

limit
Number (optional) 

This is an optional parameter. Maximum number of paths to retrieve. Default is 10.

offset
Number (optional) 

This is an optional parameter. 0-indexed offset. Default is 0.

path
String (optional) 

This is an optional parameter. The target path of data to retrieve. Default is the path of the current site.

uniquePath
Boolean (optional) 

This is an optional parameter. If true is given, the MT can return total pageviews for each uniqueness paths. However, that data does not contains page title because its spec. (Sometimes, Google Analytics will return another pageviews by same path.)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults": 2,
  "items": [
    {
      "entry": null,
      "pageviews": "56",
      "author": null,
      "path": "/",
      "title": "Your site",
      "archiveType": "index",
      "category": null,
      "startDate": null
    },
    {
      "entry": {
        "id": "1198"
      },
      "pageviews": "44",
      "author": null,
      "path": "/2015/03/exapmle.html",
      "title": "Entry title is here",
      "archiveType": "Individual",
      "category": null,
      "startDate": null
    },
  ],
  "totals": {
    "pageviews": "329"
  }
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Unauthorized",
    "code": 401
  }
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Readied provider is not found",
    "code": "404"
  }
}

Retrieve a list of page view data for each date
GET/sites/{site_id}/stats/date/pageviews{?startDate,endDate,limit,offset,path,uniquePath}

Retrieve a list of page view data for each date from the provider.

Authentication required.

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/stats/date/pageviews?startDate=&endDate=&limit=&offset=&path=&uniquePath=
URI Parameters
HideShow
site_id
Number (required) 

The site ID.

startDate
String (required) 

This is an required parameter. Start date of data. The format is “YYYY-MM-DD”.

endDate
String (required) 

This is an required parameter. End date of data. The format is “YYYY-MM-DD”.

limit
Number (optional) 

This is an optional parameter. Maximum number of paths to retrieve. Default is 10.

offset
Number (optional) 

This is an optional parameter. 0-indexed offset. Default is 0.

path
String (optional) 

This is an optional parameter. The target path of data to retrieve. Default is the path of the current site.

uniquePath
Boolean (optional) 

This is an optional parameter. If true is given, the MT can return total pageviews for each uniqueness paths. However, that data does not contains page title because its spec. (Sometimes, Google Analytics will return another pageviews by same path.)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults": 6,
  "items": [
    {
      "visits": "1",
      "date": "2015-05-20"
    },
    {
      "visits": "1",
      "date": "2015-05-21"
    },
    {
      "visits": "2",
      "date": "2015-05-22"
    },
    {
      "visits": "1",
      "date": "2015-05-23"
    },
    {
      "visits": "1",
      "date": "2015-05-24"
    },
    {
      "visits": "4",
      "date": "2015-05-25"
    }
  ],
  "totals": {
    "visits": "10"
  }
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Unauthorized",
    "code": 401
  }
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Readied provider is not found",
    "code": "404"
  }
}

Provider

Retrieve current provider
GET/sites/{site_id}/stats/provider

Authentication required.

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/stats/provider
URI Parameters
HideShow
site_id
Number (required) 

The site ID.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "id": "GoogleAnalytics"
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Unauthorized",
    "code": 401
  }
}

Templates

This is the Templates resource.

Property Name Type Data Type Database Column Private Read Only Description Version
archiveTypes ARRAY Templatemap Y Y This archive types for this template. v2
archiveType.id value Number mt_templatemap.templatemap_id Y Y The ID for this archive type. v2
archiveType.isPreferred value boolean mt_templatemap.templatemap_is_preferred Y Y
true
This archive type is preferred in all archive types of the requested template.
false
This archive type not is preferred in all archive types of the requested template.
 v2
archiveType.fileTemplate value String mt_templatemap.templatemap_file_template Y Y The file template for this archive type. v2
archiveType.archiveType value String mt_templatemap.templatemap_archive_type Y Y The archive type for this archive type. v2
archiveType.buildType value String mt_templatemap.templatemap_build_type Y Y The build type for this archive type. v2
archiveType.updatable value boolean Y Y
true
The user who accessed can update this archive type.
false
The user who accessed cannot update this archive type.
 v2
updatable value boolean Y Y
true
The user who accessed can update this template.
false
The user who accessed cannot update this template.
 v2
blog Object Blog Y Y The blog of this template. v2
blog.id value Number mt_template.template_blog_id Y Y The ID of the blog that contains this template. v2
buildType value String mt_template.template_build_type Y The build type for this template. Available value is follows.
0
never publish this template.
1
publish this template whenever its contents are updated or affected by a change.
2
publish this template when a publish request received.
3
publish this template on demand, but do not publish a file to the file system.
4
publish this template in the background.
5
currently not in use.
 v2
createdBy Object User Y Y Created user of this template. v2
createdBy.id value Number mt_template.template_created_by Y Y The ID of this template creator. v2
createdBy.displayName value String mt_author.author_nickname Y Y The display name of this template creator. v2
createdBy.userpicUrl value String mt_author.author_userpic_url Y Y The URL of this template creator’s userpic. The userpic will be made by UserpicThumbnailSize and UserpicAllowRect settings. If user does not set own userpic, will be returned empty string. v2
createdDate value iso 8601 datetime mt_template.template_created_on Y Y Created date of this template. v2
customFields ARRAY Field Y Y The list of customfields data of this template. v2
customField.basename value String mt_field.field_basename Y Y The basename of this customfield. v2
customField.value value String mt_template_meta.* Y The value of this customfield. v2
id value Number mt_template.template_id Y Y The ID for this template. v2
linkToFie value String mt_template.template_linked_file Y The linked output filename for this template. v2
modifiedBy Object User Y Y Last modified user of this template. v2
modifiedBy.id value Number mt_template.template_modified_by Y Y The ID of this template modifier. v2
modifiedBy.displayName value String mt_author.author_nickname Y Y The display name of this template modifier. v2
modifiedBy.userpicUrl value String mt_author.author_userpic_url Y Y The URL of this template modifier’s userpic. The userpic modifiedDate value
will be made by UserpicThumbnailSize and UserpicAllowRect settings. If user does not set own userpic, will be returned empty string. v2
name value String mt_template.template_name Y The name for this template. v2
outputFile value String mt_template.template_outfile Y The output filename for this template. v2
text value String mt_template.template_text Y The text for this template. v2
type value String mt_template.template_type Y The type for this template. v2
templateType value String mt_template.template_identifier Y The identifier for this template. v2

{ “createdBy”: { “userpicUrl”: null, “id”: “1”, “displayName”: “Yuji Takayama” }, “name”: “HTML Header”, “updatable”: true, “blog”: { “id”: “1” }, “text”: " <meta name=“viewport” content=“width=device-width,initial-scale=1”>\n <link rel=“stylesheet” href="<$mt:Link template=“styles” encode_html=“1”$>">\n \n <mt:Assets tag="@SITE_FAVICON" limit=“1”><link rel=“shortcut icon” href="<$mt:AssetURL encode_html=“1”$>"></mt:Assets>\n <link rel=“start” href="<$mt:BlogURL encode_html=“1”$>">\n <link rel=“alternate” type=“application/atom+xml” title=“Recent Entries” href="<$mt:Link template=“feed_recent”$>" />\n <$mt:CanonicalLink$>\n <$mt:StatsSnippet$>\n", “linkToFile”: “”, “createdDate”: “2015-05-22T13:19:53+09:00”, “id”: “33”, “type”: “custom”, “modifiedDate”: “2015-05-22T13:19:53+09:00”, “customFields”: [] }

Templates

Retrieve a list of templates
GET/sites/{site_id}/templates{?site_id,limit,offset,sortBy,sortOrder,fields,searchFields,search,includeIds,excludeIds,type}

Retrieve a list of templates.

Authentication required.

Permissions

  • edit_templates

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/templates?site_id=&limit=&offset=&sortBy=&sortOrder=&fields=&searchFields=&search=&includeIds=&excludeIds=&type=
URI Parameters
HideShow
site_id
number (required) 

The site ID. If 0 specified, will load from global template in the system.

search
string (optional) 

Search query.

searchFields
string (optional) Default: label 

The comma separated list of field names to search.

limit
number (optional) Default: 10 

Maximum number of templates to retrieve.

offset
number (optional) Default: 0 

0-indexed offset.

sortBy
string (optional) Default: name 
id
Sort by the ID of each template.
name
Sort by the name of each template.
created_on
Sort by the created time of each template.
modified_on
Sort by the modified time of each template.
created_by
Sort by the ID of user who created each template.
modified_by
Sort by the ID of user who modified each template.
type
Sort by the type of each template.
sortOrder
string (optional) Default: descend 
descend
Return templates in descending order. For sorting by date, it means from newest to oldest.
ascend
Return templates in ascending order. For sorting by date, it means from oldest to newest.
fields
string (optional) 

The field list to retrieve as part of the Templates resource. The list of field names should be separated by commas. If this parameter is not specified, all fields will be returned.

includeIds
string (optional) 

The comma separated list of template IDs to include in result.

excludeIds
string (optional) 

The comma separated list of template IDSs to exclude from result.

type
string (optional) 

Filter by template type. The list should be separated by commas. (e.g. archive, custom, index, individual, page etc…)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults": "29",
  "items": [
    {
      "createdBy": {
        "userpicUrl": null,
        "id": "1",
        "displayName": "Yuji Takayama"
      },
      "name": "HTML Header",
      "updatable": true,
      "blog": {
        "id": "1"
      },
      "text": "    <meta name=\"viewport\" content=\"width=device-width,initial-scale=1\">\n    <link rel=\"stylesheet\" href=\"<$mt:Link template=\"styles\" encode_html=\"1\"$>\">\n    <!--[if lt IE 9]>\n    <link rel=\"stylesheet\" href=\"<$mt:Link template=\"styles_ie\" encode_html=\"1\"$>\">\n    <script src=\"<$mt:SupportDirectoryURL encode_html=\"1\"$>theme_static/rainier/js/html5shiv.js\"></script>\n    <![endif]-->\n    <mt:Assets tag=\"@SITE_FAVICON\" limit=\"1\"><link rel=\"shortcut icon\" href=\"<$mt:AssetURL encode_html=\"1\"$>\"></mt:Assets>\n    <link rel=\"start\" href=\"<$mt:BlogURL encode_html=\"1\"$>\">\n    <link rel=\"alternate\" type=\"application/atom+xml\" title=\"Recent Entries\" href=\"<$mt:Link template=\"feed_recent\"$>\" />\n    <$mt:CanonicalLink$>\n    <$mt:StatsSnippet$>\n",
      "linkToFile": "",
      "createdDate": "2015-05-22T13:19:53+09:00",
      "id": "33",
      "type": "custom",
      "modifiedDate": "2015-05-22T13:19:53+09:00",
      "customFields": []
    },
    {
      "outputFile": "mt-theme-scale2.js",
      "createdBy": {
        "userpicUrl": null,
        "id": "1",
        "displayName": "Yuji Takayama"
      },
      "name": "JavaScript - Theme",
      "updatable": true,
      "blog": {
        "id": "1"
      },
      "buildType": "Static",
      "templateType": "javascript_theme",
      "text": "$(function() {\n    $('<select />').appendTo('header [role=\"navigation\"]');\n\n    $('<option />', {\n        'value': '',\n        'text': 'Menu',\n        'selected': 'selected'\n    }).appendTo('header [role=\"navigation\"] > select');\n\n    $('header [role=\"navigation\"] a').each(function() {\n        var el = $(this);\n        $('<option />', {\n            'value': el.attr('href'),\n            'text': el.text()\n        }).appendTo('header [role=\"navigation\"] > select');\n    });\n\n    $('header [role=\"navigation\"] > select, .widget-archive-dropdown select').change(function() {\n        window.location = $(this).find('option:selected').val();\n    });\n});\n",
      "linkToFile": "",
      "type": "index",
      "id": "9",
      "createdDate": "2015-05-22T13:19:53+09:00",
      "modifiedDate": "2015-05-22T13:19:53+09:00",
      "customFields": []
    }
  ]
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Unauthorized",
    "code": 401
  }
}
Response  403
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Do not have permission to retrieve the list of templates.",
    "code": "403"
  }
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Site not found",
    "code": "404"
  }
}
Response  500
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Some error message is here",
    "code": "500"
  }
}

Retrieve a single template by its ID
GET/sites/{site_id}/templates/{template_id}{?fields}

Retrieve a single template by its ID.

Authentication required.

Permissions

  • edit_templates

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/templates/template_id?fields=
URI Parameters
HideShow
site_id
number (required) 

The site ID. If 0 specified, will load from global template in the system.

template_id
number (required) 

The template ID.

fields
string (optional) 

The field list to retrieve as part of the Templates resource. The list of field names should be separated by commas. If this parameter is not specified, all fields will be returned.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "createdBy": {
    "userpicUrl": null,
    "id": "1",
    "displayName": "Yuji Takayama"
  },
  "name": "HTML Header",
  "updatable": true,
  "blog": {
    "id": "1"
  },
  "text": "    <meta name=\"viewport\" content=\"width=device-width,initial-scale=1\">\n    <link rel=\"stylesheet\" href=\"<$mt:Link template=\"styles\" encode_html=\"1\"$>\">\n    <!--[if lt IE 9]>\n    <link rel=\"stylesheet\" href=\"<$mt:Link template=\"styles_ie\" encode_html=\"1\"$>\">\n    <script src=\"<$mt:SupportDirectoryURL encode_html=\"1\"$>theme_static/rainier/js/html5shiv.js\"></script>\n    <![endif]-->\n    <mt:Assets tag=\"@SITE_FAVICON\" limit=\"1\"><link rel=\"shortcut icon\" href=\"<$mt:AssetURL encode_html=\"1\"$>\"></mt:Assets>\n    <link rel=\"start\" href=\"<$mt:BlogURL encode_html=\"1\"$>\">\n    <link rel=\"alternate\" type=\"application/atom+xml\" title=\"Recent Entries\" href=\"<$mt:Link template=\"feed_recent\"$>\" />\n    <$mt:CanonicalLink$>\n    <$mt:StatsSnippet$>\n",
  "linkToFile": "",
  "createdDate": "2015-05-22T13:19:53+09:00",
  "id": "33",
  "type": "custom",
  "modifiedDate": "2015-05-22T13:19:53+09:00",
  "customFields": []
}

+ Response 401 (application/json)

        {
          "error": {
            "message": "Unauthorized",
            "code": 401
          }
        }

+ Response 403 (application/json)

        {
          "error": {
            "message": "Do not have permission to retrieve the list of templates.",
            "code": "403"
          }
        }

+ Response 404 (application/json)

        {
          "error": {
            "message": "Site not found / Template not found",
            "code": "404"
          }
        }

+ Response 500 (application/json)

        {
          "error": {
            "message": "Some error message is here",
            "code": "500"
          }
        }

Create a new template
POST/sites/{site_id}/templates

Create a new template.

Authentication required.

Permissions

  • edit_templates

Example URI

POST http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/templates
URI Parameters
HideShow
site_id
number (required) 

The site ID. If 0 specified, will create into the global template in the system.

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Body
template={ "name": "New Template", "text": "some template code here", "linkToFile": "", "type": "custom" }
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "createdBy": {
    "userpicUrl": null,
    "id": "1",
    "displayName": "Yuji Takayama"
  },
  "name": "New Template",
  "updatable": true,
  "blog": {
    "id": "1"
  },
  "text": "some template code here",
  "linkToFile": "",
  "createdDate": "2015-06-29T16:47:09+09:00",
  "id": "152",
  "type": "custom",
  "modifiedDate": "2015-06-29T16:47:09+09:00",
  "customFields": []
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Unauthorized",
    "code": 401
  }
}
Response  403
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Do not have permission to retrieve a template.",
    "code": "403"
  }
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Site not found",
    "code": "404"
  }
}
Response  500
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Some error message is here",
    "code": "500"
  }
}

Update a template
PUT/sites/{site_id}/templates/{template_id}

Update a template.

Authentication required.

This method accepts PUT or POST with __method=PUT.

Permissions

  • edit_templates

Example URI

PUT http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/templates/template_id
URI Parameters
HideShow
site_id
number (required) 

The site ID. If 0 specified, will update a global template in the system.

template_id
number (required) 

The template ID.

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Body
template={ "name": "new template name" }
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "createdBy": {
    "userpicUrl": null,
    "id": "1",
    "displayName": "Yuji Takayama"
  },
  "name": "New Template name",
  "updatable": true,
  "blog": {
    "id": "1"
  },
  "text": "some template code here",
  "linkToFile": "",
  "createdDate": "2015-06-29T16:47:09+09:00",
  "id": "152",
  "type": "custom",
  "modifiedDate": "2015-06-29T16:47:09+09:00",
  "customFields": []
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Unauthorized",
    "code": 401
  }
}
Response  403
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Do not have permission to update a template.",
    "code": "403"
  }
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Site not found / Template not found",
    "code": "404"
  }
}
Response  405
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Request method is not PUT or 'POST' with __PUT"
    "code": "405"
  }
}
Response  500
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Some error message is here",
    "code": "500"
  }
}

Delete a template
DELETE/sites/{site_id}/templates/{template_id}

Delete a template.

Authentication required.

This method accepts DELETE or POST with __method=DELETE.

Permissions

  • edit_templates

Example URI

DELETE http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/templates/template_id
URI Parameters
HideShow
site_id
number (required) 

The site ID. If 0 specified, delete from global template in the system.

template_id
number (required) 

The template ID.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "createdBy": {
    "userpicUrl": null,
    "id": "1",
    "displayName": "Yuji Takayama"
  },
  "name": "New Template name",
  "updatable": true,
  "blog": {
    "id": "1"
  },
  "text": "some template code here",
  "linkToFile": "",
  "createdDate": "2015-06-29T16:47:09+09:00",
  "id": "152",
  "type": "custom",
  "modifiedDate": "2015-06-29T16:47:09+09:00",
  "customFields": []
}
Response  401
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Unauthorized",
    "code": 401
  }
}
Response  403
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Do not have permission to delete a template.",
    "code": "403"
  }
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Site not found / Template not found",
    "code": "404"
  }
}
Response  405
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Request method is not PUT or 'POST' with __PUT"
    "code": "405"
  }
}
Response  500
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Some error message is here",
    "code": "500"
  }
}

Publish a template
POST/sites/{site_id}/templates/{template_id}/publish

Publish (in other words rebuild) a template.

Authentication required.

Only available for following templates

  • index

  • archive

  • individual

  • page

  • category

Permissions

  • rebuild

Example URI

POST http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/templates/template_id/publish
URI Parameters
HideShow
site_id
number (required) 

The site ID

template_id
number (required) 

The template ID.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": "success"
}
Response  400
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Cannot publish [template type] template.",
    "code": "400"
  }
}
Response  403
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Do not have permission to publish a template.",
    "code": "403"
  }
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Site not found / Template not found",
    "code": "404"
  }
}
Response  500
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Some error message is here",
    "code": "500"
  }
}

Make a clone
POST/sites/{site_id}/templates/{template_id}/clone

Make a clone of a template.

Authentication required.

Permissions

  • edit_templates

Example URI

POST http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/templates/template_id/clone
URI Parameters
HideShow
site_id
number (required) 

The site ID. If 0 specified, refresh a global template in the system.

template_id
number (required) 

The template ID.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": "success"
}
Response  403
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Do not have permission to clone a template.",
    "code": "403"
  }
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Site not found / Template not found",
    "code": "404"
  }
}
Response  500
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Some error message is here",
    "code": "500"
  }
}

Refresh

Reset template text
POST/sites/{site_id}/templates/{template_id}/refresh

Reset template text to theme default or tempalte_set default.

Authentication required.

Permissions

  • edit_templates

Example URI

POST http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/templates/template_id/refresh
URI Parameters
HideShow
site_id
number (required) 

The site ID. If 0 specified, refresh a global template in the system.

template_id
number (required) 

The template ID.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "messages": [
    "「New Template name」を初期化します。"
  ],
  "status": "success"
}
Response  403
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Do not have permission to refresh a template.",
    "code": "403"
  }
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Site not found / Template not found",
    "code": "404"
  }
}
Response  500
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Some error message is here",
    "code": "500"
  }
}

Reset all template text
POST/sites/{site_id}/refresh_templates{?refresh_type}

Reset all templates to default.

Authentication required.

Permissions

  • edit_templates

Example URI

POST http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/refresh_templates?refresh_type=
URI Parameters
HideShow
site_id
number (required) 

The site ID. If 0 specified, refresh a global template in the system.

refresh_type
string (optional) Default: refresh 

The type of refresh mode.

refresh
Refresh all templates. However, A template that created by user will never refreshed and never removed from a site.
clean
Refresh all templates. In this mode, A template that created by user will removed from a site.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": "success"
}
Response  403
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Do not have permission to refresh templates of the request site.",
    "code": "403"
  }
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Site not found",
    "code": "404"
  }
}
Response  500
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Some error message is here",
    "code": "500"
  }
}

Preview

Make a preview
POST/sites/{site_id}/templates/preview{?raw}

Make a template preview by specified data.

Authentication required.

type parameter in the Templates resource is required.

Permissions

  • edit_templates

Example URI

POST http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/templates/preview?raw=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

raw
number (optional) 

If specify “1”, will be returned preview contents.

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Body
template={ "name": "New Template", "text": "some template code here", "type": "custom" }
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": "success",
  "preview": "http://example.com/index.html"
}
Response  403
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Do not have permission to get template preview.",
    "code": "403"
  }
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Site not found",
    "code": "404"
  }
}
Response  500
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Some error message is here",
    "code": "500"
  }
}

Make a preview for an existing template
POST/sites/{site_id}/templates/{template_id}/preview{?raw}

Authentication required.

Only available for following templates

  • index

  • archive

  • individual

  • page

  • category

  • template parameter is required. If you just want to get preview template from existing data, you should provide template parameter with empty json.

Permissions

  • edit_templates

Example URI

POST http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/templates/template_id/preview?raw=
URI Parameters
HideShow
site_id
number (required) 

The site ID.

template_id
number (required) 

The template ID.

raw
number (optional) 

If specify “1”, will be returned preview contents.

Request  Templates resource
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
Body
template={}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": "success",
  "preview": "http://example.com/index.html"
}
Response  403
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Do not have permission to get template preview.",
    "code": "403"
  }
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Site not found / Template not found",
    "code": "404"
  }
}
Response  500
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "message": "Some error message is here",
    "code": "500"
  }
}

Themes

This is the Themes resource. The Themes resource is not stored in the database.

Property Name Type Data Type Database Column Private Read Only Description Version
authorLink value string - Y Y The author link of this theme. v2
authorName value string - Y Y The author name of this theme. v2
current value boolean - Y Y DEPRECATAD
description value string - Y Y The description for this theme. v2
id value string - Y Y The ID for this theme. v2
inUse value boolean - Y Y This property is displayed only in system scope.
true
This theme is in used by any site.
false
This theme is not in use.
 v2
label value string - Y Y The label for this theme. v2
uninstallable value boolean - Y Y
true
This theme is able to uninstall.
false
This theme is not able to uninstall.
 v2
version value string - Y Y The version number for this theme. v2

{ “authorName”: “Six Apart Ltd.”, “authorLink”: "http://www.movabletype.org/", “version”: “1.14”, “description”: ““Rainier” is a customizable Responsive Web Design theme, designed for blogs. In addition to multi-device viewing support, provided by Media Query (CSS), Movable Type functions make customizing navigational contents as well as image elements, such as logos, headers, very simple.”, “uninstallable”: false, “inUse”: true, “id”: “rainier”, “label”: “Rainier” }

Themes

Retrieve a list of themes
GET/themes

Retrieve a list of all of the installed theme.

Authentication required

Permissions

  • manage_themes

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/themes
Request
HideShow
Headers
X-MT-Authorization: MTAuth accessToken=<Token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults": 9,
  "items": [
    {
      "authorName": "Six Apart Ltd.",
      "authorLink": "http://www.movabletype.org/",
      "version": "1.14",
      "description": "\"Rainier\" is a customizable Responsive Web Design theme, designed for blogs. In addition to multi-device viewing support, provided by Media Query (CSS), Movable Type functions make customizing navigational contents as well as image elements, such as logos, headers, very simple.",
      "uninstallable": false,
      "inUse": true,
      "id": "rainier",
      "label": "Rainier"
    },
    {
      "authorName": "Six Apart Ltd.",
      "authorLink": "http://www.movabletype.org/",
      "version": "1.3",
      "description": "Create a blog portal that aggregates contents from several blogs in one website.",
      "uninstallable": false,
      "inUse": false,
      "label": "Classic Website",
      "id": "classic_website"
    },
    {
      "authorName": "Six Apart Ltd.",
      "authorLink": "http://www.sixapart.com/",
      "version": "1.11",
      "description": "Professional designed, well structured and easily adaptable web site. You can customize default pages, footer and top navigation easily.",
      "uninstallable": false,
      "inUse": false,
      "label": "Professional Website",
      "id": "professional_website"
    },
    {
      "authorName": "Six Apart Ltd",
      "authorLink": "http://www.sixapart.com/",
      "version": "1.44",
      "description": "Eiger is a customizable Responsive Web Design theme, designed for blogs and corporate websites. In addition to multi-device viewing support, provided via Media Query (CSS), Movable Type functions make customizing navigational contents as well as image elements, such as logos, headers or banners, very simple.",
      "uninstallable": false,
      "inUse": false,
      "label": "Eiger",
      "id": "eiger"
    },
    {
      "authorName": "Six Apart Ltd.",
      "authorLink": "http://www.movabletype.org/",
      "version": "1.3",
      "description": "Pico is a microblogging theme, designed for keeping things simple to handle frequent updates. To put the focus on content we've moved the sidebars below the list of posts.",
      "uninstallable": false,
      "inUse": false,
      "label": "Pico",
      "id": "pico"
    },
    {
      "authorName": "Six Apart Ltd.",
      "authorLink": "http://www.movabletype.org/",
      "version": "1.3",
      "description": "A traditional blogging design that comes with plenty of styles and a selection of 2 column / 3 column layouts. Best for use in standard blog publishing applications.",
      "uninstallable": false,
      "inUse": false,
      "label": "Classic Blog",
      "id": "classic_blog"
    },
    {
      "authorName": "Six Apart Ltd.",
      "authorLink": "http://www.sixapart.com/",
      "version": "1.01",
      "description": "Increase reader engagement - deploy features to your website that make it easier for your readers to engage with your content and your company.",
      "uninstallable": false,
      "inUse": false,
      "label": "Community Blog",
      "id": "mt_community_blog"
    },
    {
      "authorName": "Six Apart Ltd.",
      "authorLink": "http://www.sixapart.com/",
      "version": "1.01",
      "description": "Create forums where users can post topics and responses to topics.",
      "uninstallable": false,
      "inUse": false,
      "label": "Community Forum",
      "id": "mt_community_forum"
    },
    {
      "authorName": "Six Apart Ltd.",
      "authorLink": "http://www.sixapart.com/",
      "version": "1.11",
      "description": "Create a blog as a part of structured website. This works best with Professional Website theme.",
      "uninstallable": false,
      "inUse": false,
      "label": "Professional Blog",
      "id": "professional_blog"
    }
  ]
}

Retrieve a single theme
GET/themes/{theme_id}

Retrieve a single theme by its ID.

Authentication required

Permissions

  • manage_themes

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/themes/theme_id
URI Parameters
HideShow
theme_id
string (required) 

The theme ID.

Request
HideShow
Headers
X-MT-Authorization: MTAuth accessToken=<Token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "authorName": "Six Apart Ltd.",
  "authorLink": "http://www.movabletype.org/",
  "version": "1.14",
  "description": "\"Rainier\" is a customizable Responsive Web Design theme, designed for blogs. In addition to multi-device viewing support, provided by Media Query (CSS), Movable Type functions make customizing navigational contents as well as image elements, such as logos, headers, very simple.",
  "uninstallable": false,
  "inUse": false,
  "id": "rainier",
  "label": "Rainier"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "code": 404,
    "message": "Theme not found"
  }
}

Utilities

Apply theme
POST/sites/{site_id}/themes/{theme_id}/apply

Apply theme to site.

Authentication required

Permissions

  • manage_themes

Example URI

POST http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/themes/theme_id/apply
URI Parameters
HideShow
site_id
number (required) 

The site ID.

theme_id
string (required) 

The theme ID.

Request
HideShow
Headers
X-MT-Authorization: MTAuth accessToken=<Token>
Response  200
HideShow
Headers
Content-Type: appication/json
Body
{
  "status": "success"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "code": 404,
    "message": "Theme not found"
  }
}

Uninstall theme
DELETE/themes/{theme_id}

Uninstall theme from MT.
When successful, you can take Themes Resource that was deleted. However, this theme is already removed from the Movable Type. You cannot apply this theme to.

Authentication required

Permissions

  • manage_themes

Example URI

DELETE http://your-host/path-to-mt/mt-data-api.cgi/v3/themes/theme_id
URI Parameters
HideShow
theme_id
string (required) 

The theme ID.

Request
HideShow
Headers
X-MT-Authorization: MTAuth accessToken=<Token>
Response  200
HideShow
Headers
Content-Type: appication/json
Body
{
  "authorName": null,
  "authorLink": "",
  "version": "1.0",
  "description": "",
  "uninstallable": true,
  "inUse": false,
  "id": "theme_from_test",
  "label": "Theme from Rainier"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "code": 404,
    "message": "Theme not found"
  }
}

Export theme
POST/sites/{site_id}/export_theme

Exporting current theme element as a new theme.

Authentication required

This endpoint will export current theme elements of specified site into theme directory.

Permissions

  • manage_themes

Example URI

POST http://your-host/path-to-mt/mt-data-api.cgi/v3/sites/site_id/export_theme
URI Parameters
HideShow
site_id
number (required) 

The site ID.

Request
HideShow
Headers
X-MT-Authorization: MTAuth accessToken=<Token>
Response  200
HideShow
Headers
Content-Type: appication/json
Body
{
  "status": "success"
}
Response  404
HideShow
Headers
Content-Type: application/json
Body
{
  "error": {
    "code": 404,
    "message": "Theme not found"
  }
}

Users

This is the Users resource.

Property Name Type Data Type Database Column Private Read Only Description Version
createdBy Object User - Y Y Created user of this user. v2
createdBy.displayName value string mt_author.author_nickname Y Y The display name of this user creator. v2
createdBy.id value number mt_author.author_created_by Y Y The ID of this user creator. v2
createdBy.userpicUrl value string mt_author.author_userpic_url Y The URL of this user creator’s userpic. The userpic will be made by UserpicThumbnailSize and UserpicAllowRect settings. If user does not set own userpic, will be returned empty string. v2
createdDate value iso 8601 datetime mt_author.author_created_on - Y Created date of this user. v2
customFields value Field - - Y The list of customfields data of this user. v2
customField.basename value string mt_field.field_basename - Y The basename of this customfield. v2
customField.value value string mt_author_meta.* - - The value of this customfield. v2
dateFormat value string mt_author.author_date_format Y The date formatting for this user. v2
displayName value string mt_author.author_nickname The public display name for this user. v1
email value string mt_author.author_email Y The email address for this user. v1
id value number mt_author.author_id Y Y The unique ID for this user. v1
isSuperuser value boolean Y Y
true
This user have permission for system administration.
false
This user does not have permission for system administration.
 v2
language value string mt_author.author_preferred_language The preferred language for this user.
Available values
  • de
  • en-us
  • es
  • fr
  • nl
  • ja
 v1
lockedOut value boolean mt_author.author_locked_out_time Y Y
true
This user is currently locked out.
false
This user is not locked out.
 v2
modifiedBy Object User - - Y Last modified user of this user. v2
modifiedBy.displayName value string mt_author.author_nickname - Y The display name of this user modifier. v2
modifiedBy.id value number mt_author.author_modified_by - Y The ID of this user modifier. v2
modifiedBy.userpicUrl value string mt_author.author_userpic_url - Y The URL of this user modifier’s userpic. The userpic will be made by UserpicThumbnailSize and UserpicAllowRect settings. If user does not set own userpic, will be returned empty string. v2
modifiedDate value iso 8601 datetime mt_author.author_modified_on - Y Last modified date of this user. v2
name value string mt_author.author_name The account name for this user. [update in v2] This column was changed to updatable from v2. v1
password value string mt_author.author_password Y Write Only The password for this user. This property is write only. v2
updatable value boolean Y
true
The user who accessed can update this user.
false
The user who accessed cannot update this user.
 v1
url value string mt_author.author_url The web site URL for this user. v1
userpicUrl value string Y The profile photo URL for this user. The userpic will be made by UserpicThumbnailSize and UserpicAllowRect settings. If user does not set own userpic, will be returned empty string. v1
status value string mt_author.author_status Y The status for this user. Available value is follows.
Active
The status is active. The user can do anything within his/her permissions.
Disabled
The status is disabled. The user cannot do anything.
Pending
The status is pending. The user is waiting for approval by the administrator. Therefore, this user cannot do anything.
 v2
systemPermissions ARRAY string - Y - The list of system permissions which this user have. Only system administrator can get this property v2
tagDelimiter value string mt_author.author_entry_prefs Y The tag delimiter character for this user. Available value is follow.
comma
Separator character is single comma.
space
Separator character is single space
 v2
textFormat value string mt_author.author_text_format Y The text formatting for this user. v2

{ “status” : “Active”, “createdBy” : { “userpicUrl” : null, “id” : “1”, “displayName” : “Yuji Takayama” }, “updatable” : true, “lockedOut” : false, “isSuperuser” : true, “dateFormat” : “relative”, “systemPermissions” : [ “administer”, “create_website”, “create_blog”, “edit_templates”, “manage_plugins”, “view_log” ], “email” : "ytakayama@sixapart.com", “userpicUrl” : null, “url” : “”, “id” : “1”, “tagDelimiter” : “comma”, “displayName” : “Yuji Takayama”, “modifiedBy” : { “userpicUrl” : null, “id” : “1”, “displayName” : “Yuji Takayama” }, “modifiedDate” : “2015-03-26T17:12:18+09:00”, “language” : “en-us”, “name” : “takayama”, “textFormat” : “0”, “createdDate” : “2015-03-23T14:53:52+09:00”, “customFields” : [] }

Users

Retrieve a list of users
GET/users{?search,searchFields,limit,offset,sortBy,sortOrder,fields,includeIds,excludeIds,status,lockout,dateField,dateFrom,dateTo}

Retrieve a list of users. This list does not include the commenter.

Authentication required if you want to include inactive users or to get the private properties.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to retrieve the list of users.

Permissions

  • administer
    • for retrieve non-active users
    • for read private properties

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/users?search=&searchFields=&limit=&offset=&sortBy=&sortOrder=&fields=&includeIds=&excludeIds=&status=&lockout=&dateField=&dateFrom=&dateTo=
URI Parameters
HideShow
search
string (optional) 

Search query.

searchFields
string (optional) Default: name,displayName,email,url 

The comma separated field name list to search.

limit
number (optional) Default: 10 

Maximum number of users to retrieve.

offset
number (optional) Default: 0 

0-indexed offset.

sortBy
string (optional) Default: name 

The field name for sort. You can specify one of following values

  • id
  • name

sortOrder
string (optional) Default: descend 
descend
(default) Return users in descending order.
ascend
Return users in ascending order.
fields
string (optional) 

The field list to retrieve as part of the Users resource. That list should be separated by comma. If this parameter is not specified, All fields will be returned.

includeIds
string (optional) 

The comma separated ID list of users to include to result.

excludeIds
string (optional) 

The comma separated ID list of users to exclude from result.

status
string (optional) 

Filter by users’s status.

active
status is Active
disabled
status is Disabled.
pending
status is Pending

lockout
string (required) 

Filter by user’s lockout status.

locked_out
Locked out user only
not_locked_out
Not locked out user only

dateField
string (optional) Default: created_on 

Specifies the field name to be used as a date field for filtering. (new in v3)

dateFrom
string (optional) 

The start date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

dateTo
string (optional) 

The end date to filtering. Specify in “YYYY-MM-DD” format. (new in v3)

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "totalResults": 1,
  "items": [
    {
      "status": "Active",
      "createdBy": {
        "userpicUrl": null,
        "id": "1",
        "displayName": "Yuji Takayama"
      },
      "updatable": true,
      "lockedOut": false,
      "isSuperuser": true,
      "dateFormat": "relative",
      "systemPermissions": [
        "administer",
        "create_website",
        "create_blog",
        "edit_templates",
        "manage_plugins",
        "view_log"
      ],
      "email": "ytakayama@sixapart.com",
      "userpicUrl": null,
      "url": "",
      "id": "1",
      "tagDelimiter": "comma",
      "displayName": "Yuji Takayama",
      "modifiedBy": {
        "userpicUrl": null,
        "id": "1",
        "displayName": "Yuji Takayama"
      },
      "modifiedDate": "2015-03-26T17:12:18+09:00",
      "language": "en-us",
      "name": "takayama",
      "textFormat": "0",
      "createdDate": "2015-03-23T14:53:52+09:00",
      "customFields": []
    }
  ]
}

Create a new user
POST/users

Create a new user.

Authentication required.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to create a new user.

Permissions

  • administer

Request Body Parameters

Name Type Required Default Description
user Object Yes Single Users resource

Example URI

POST http://your-host/path-to-mt/mt-data-api.cgi/v3/users
Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
X-MT-Authorization: MTAuth accessToken=<Token>
Body
user={"email" : "aikawa@example.com","displayName" : "Ichiro Aikawa","name" : "aikawa","password":"password"}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": "Active",
  "createdBy": {
    "userpicUrl": null,
    "id": "1",
    "displayName": "Yuji Takayama"
  },
  "updatable": true,
  "lockedOut": false,
  "isSuperuser": false,
  "dateFormat": "relative",
  "systemPermissions": [],
  "email": "aikawa@example.com",
  "userpicUrl": null,
  "url": null,
  "id": "2",
  "tagDelimiter": "comma",
  "displayName": "Ichiro Aikawa",
  "modifiedDate": "2015-03-27T10:45:43+09:00",
  "language": "ja",
  "name": "aikawa",
  "textFormat": 0,
  "createdDate": "2015-03-27T10:45:43+09:00",
  "customFields": []
}

Retrieve a single user by ID
GET/users/{user_id}{?fields}

Retrieve a single user by ID.

Authentication required if want to get inactive user or want to get the private properties.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to get the user.
404 Not Found User not found.

Permissions

  • administer

Example URI

GET http://your-host/path-to-mt/mt-data-api.cgi/v3/users/user_id?fields=
URI Parameters
HideShow
user_id
number or the word 'me' (required) 

The user ID.

fields
string (optional) 

The field list to retrieve as part of the Users resource. That list should be separated by comma. If this parameter is not specified, All fields will be returned.

Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": "Active",
  "createdBy": {
    "userpicUrl": null,
    "id": "1",
    "displayName": "Yuji Takayama"
  },
  "updatable": true,
  "lockedOut": false,
  "isSuperuser": true,
  "dateFormat": "relative",
  "systemPermissions": [
    "administer",
    "create_website",
    "create_blog",
    "edit_templates",
    "manage_plugins",
    "view_log"
  ],
  "email": "ytakayama@sixapart.com",
  "userpicUrl": null,
  "url": "",
  "id": "1",
  "tagDelimiter": "comma",
  "displayName": "Yuji Takayama",
  "modifiedBy": {
    "userpicUrl": null,
    "id": "1",
    "displayName": "Yuji Takayama"
  },
  "modifiedDate": "2015-03-26T17:12:18+09:00",
  "language": "en-us",
  "name": "takayama",
  "textFormat": "0",
  "createdDate": "2015-03-23T14:53:52+09:00",
  "customFields": []
}

Update user
PUT/users/{user_id}

Update an existing user.

Authentication required.

  • This method accepts PUT and POST with __method=PUT.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to update user.
404 Not Found User not found.
405 Method Not Allowed Request method is not ‘PUT’ or ‘POST’ with ‘__method=PUT’

Permissions

  • administer
    • If you want to update another one’s or non-active user.

Example URI

PUT http://your-host/path-to-mt/mt-data-api.cgi/v3/users/user_id
URI Parameters
HideShow
user_id
number or the word 'me' (required) 

The user ID.

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
X-MT-Authorization: MTAuth accessToken=<Token>
Body
user={"displayName": "New Name"}
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": "Active",
  "createdBy": {
    "userpicUrl": null,
    "id": "1",
    "displayName": "Yuji Takayama"
  },
  "updatable": true,
  "lockedOut": false,
  "isSuperuser": false,
  "dateFormat": "relative",
  "systemPermissions": [],
  "email": "aikawa@example.com",
  "userpicUrl": null,
  "url": null,
  "id": "2",
  "tagDelimiter": "comma",
  "displayName": "New Name",
  "modifiedDate": "2015-03-27T10:45:43+09:00",
  "language": "ja",
  "name": "aikawa",
  "textFormat": "0",
  "createdDate": "2015-03-27T10:45:43+09:00",
  "customFields": []
}

Delete user.
DELETE/users/{user_id}

Delete an existing user.

Authentication required.

  • This method accepts DELETE and POST with __method=DELETE.
  • Cannot delete oneself. Also, cannot delete system administrator.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to delete user.
404 Not Found User not found.
405 Method Not Allowed Request method is not ‘DELETE’ or ‘POST’ with ‘__method=DELETE’

Permissions

  • administer

Example URI

DELETE http://your-host/path-to-mt/mt-data-api.cgi/v3/users/user_id
URI Parameters
HideShow
user_id
number (required) 

The user ID.

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
X-MT-Authorization: MTAuth accessToken=<Token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": "Active",
  "createdBy": {
    "userpicUrl": null,
    "id": "1",
    "displayName": "Yuji Takayama"
  },
  "updatable": true,
  "lockedOut": false,
  "isSuperuser": false,
  "dateFormat": "relative",
  "systemPermissions": [],
  "email": "aikawa@example.com",
  "userpicUrl": null,
  "url": null,
  "id": "2",
  "tagDelimiter": "comma",
  "displayName": "New Name",
  "modifiedDate": "2015-03-27T10:45:43+09:00",
  "language": "ja",
  "name": "aikawa",
  "textFormat": "0",
  "createdDate": "2015-03-27T10:45:43+09:00",
  "customFields": []
}

Unlock user
POST/users/{user_id}/unlock

Unlock user account.

Authentication required.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to unlock user.
404 Not Found User not found.

Permissions

  • administer

Example URI

POST http://your-host/path-to-mt/mt-data-api.cgi/v3/users/user_id/unlock
URI Parameters
HideShow
user_id
number (required) 

The user ID.

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
X-MT-Authorization: MTAuth accessToken=<Token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": "success"
}

Send recover link by user ID
POST/users/{user_id}/recover_password

Send a email that contains the link for password recovery to user.

Authentication required.

Status Code

Code Status Description
200 OK No Errors.
403 Forbidden Do not have permission to send password recovery mail.
404 Not Found User not found.

Permissions

  • administer

Example URI

POST http://your-host/path-to-mt/mt-data-api.cgi/v3/users/user_id/recover_password
URI Parameters
HideShow
user_id
number (required) 

The user ID.

Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
X-MT-Authorization: MTAuth accessToken=<Token>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": "success",
  "message": <Result message>
}

Send recover link by email address
POST/recover_password

Send a email that contains the link for password recovery to user.
In this endpoint, to search for the user in an e-mail address but if more than one user has the same e-mail address, it will be judged by the username.

Authentication not required.

  • This method always returns successful by security reason.

Status Code

Code Status Description
200 OK No Errors.

Permissions

  • administer

  • Message Body Parameters

    • email (required, string) … The e-mail address to search for.
    • name (optional, string) … The username for to decide user.

Example URI

POST http://your-host/path-to-mt/mt-data-api.cgi/v3/recover_password
Request
HideShow
Headers
Content-Type: application/x-www-form-urlencoded
X-MT-Authorization: MTAuth accessToken=<Token>
Body
email=<Email address for user>&name=<Name for user>
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "status": "success",
  "message": <Result message>
}

Generated by aglio on 10 Feb 2022