Telegraph API

https://telegra.ph/api
Admin
The Telegraph API allows developers to programmatically interact with Telegra.ph, a minimalist...
Tokens:3,529
Snippets:12
Trust Score:5.9
Update:1 year ago
Show doc for...
Tokens:
Raw
### Get Page API Method

Source: https://telegra.ph/api/index

Use this method to get a Telegraph page. Returns a Page object on success.

```APIDOC
getPage:
  Description: Retrieves a Telegraph page.
  Parameters:
    path: String - Required. Path to the Telegraph page (in the format Title-12-31, i.e. everything that comes after http://telegra.ph/).
    return_content: Boolean (default = false) - If true, content field will be returned in Page object.
  Returns: Page object.
  Sample Request: https://api.telegra.ph/getPage/Sample-Page-12-15?return_content=true
```

--------------------------------

### Get Page List API Method

Source: https://telegra.ph/api/index

Use this method to get a list of pages belonging to a Telegraph account. Returns a PageList object, sorted by most recently created pages first.

```APIDOC
getPageList:
  Description: Retrieves a list of pages belonging to a Telegraph account, sorted by most recently created.
  Parameters:
    access_token: String - Required. Access token of the Telegraph account.
    offset: Integer (default = 0) - Sequential number of the first page to be returned.
    limit: Integer (0-200, default = 50) - Limits the number of pages to be retrieved.
  Returns: PageList object.
  Sample Request: https://api.telegra.ph/getPageList?access_token=d3b25feccb89e508a9114afb82aa421fe2a9712b963b387cc5ad71e58722&limit=3
```

--------------------------------

### Telegraph API General Information and Response Format

Source: https://telegra.ph/api/index

Describes the general structure of Telegraph API queries, supported HTTP methods (GET and POST), and the standard JSON response format, including the 'ok' field for success/failure and 'result'/'error' fields.

```APIDOC
All queries to the Telegraph API must be served over HTTPS and should be presented in this form: `https://api.telegra.ph/%method%`.
If a `path` parameter is present, you can also use this form: `https://api.telegra.ph/%method%/%path%`.

Supported HTTP methods: GET, POST.
Response format: JSON object with Boolean field `ok`. If `ok` is true, result is in `result` field. If `ok` is false, error is in `error` field (e.g. SHORT_NAME_REQUIRED).
All queries must be made using UTF-8.
```

--------------------------------

### Telegraph API: Get Account Information

Source: https://telegra.ph/api/index

This method retrieves information about a specific Telegraph account. It allows specifying which account fields to return. On success, it returns an Account object containing the requested information.

```APIDOC
Method: getAccountInfo
Description: Use this method to get information about a Telegraph account.
Returns: Account object on success.

Parameters:
  access_token: String, Required. Access token of the Telegraph account.
  fields: Array of String, default = ["short_name","author_name","author_url"]. List of account fields to return. Available fields: short_name, author_name, author_url, auth_url, page_count.

Sample request: https://api.telegra.ph/getAccountInfo?access_token=d3b25feccb89e508a9114afb82aa421fe2a9712b963b387cc5ad71e58722&fields=["short_name","page_count"]
```

--------------------------------

### Revoke Access Token API Method

Source: https://telegra.ph/api/index

Use this method to revoke access_token and generate a new one, for example, if the user would like to reset all connected sessions, or you have reasons to believe the token was compromised. On success, returns an Account object with new access_token and auth_url fields.

```APIDOC
revokeAccessToken:
  Description: Revokes the current access token and generates a new one. Useful for resetting sessions or if the token is compromised.
  Parameters:
    access_token: String - Required. Access token of the Telegraph account.
  Returns: Account object with new access_token and auth_url.
  Sample Request: https://api.telegra.ph/revokeAccessToken?access_token=d3b25feccb89e508a9114afb82aa421fe2a9712b963b387cc5ad71e58722
```

--------------------------------

### Create Page API Method

Source: https://telegra.ph/api/index

Use this method to create a new Telegraph page. On success, returns a Page object.

```APIDOC
createPage:
  Description: Creates a new Telegraph page.
  Parameters:
    access_token: String - Required. Access token of the Telegraph account.
    title: String (1-256 characters) - Required. Page title.
    author_name: String (0-128 characters) - Author name, displayed below the article's title.
    author_url: String (0-512 characters) - Profile link, opened when users click on the author's name below the title. Can be any link, not necessarily to a Telegram profile or channel.
    content: Array of Node (up to 64 KB) - Required. Content of the page.
    return_content: Boolean (default = false) - If true, a content field will be returned in the Page object.
  Returns: Page object.
  Sample Request: https://api.telegra.ph/createPage?access_token=d3b25feccb89e508a9114afb82aa421fe2a9712b963b387cc5ad71e58722&title=Sample+Page&author_name=Anonymous&content=[{\"tag\":\"p\",\"children\":[\"Hello,+world!\"]}]&return_content=true
```

--------------------------------

### Telegraph API: Create New Account

Source: https://telegra.ph/api/index

This method allows the creation of a new Telegraph account. It is useful for channel administrators to manage multiple author profiles. Upon successful creation, it returns an Account object including an access_token.

```APIDOC
Method: createAccount
Description: Use this method to create a new Telegraph account.
Returns: Account object with access_token.

Parameters:
  short_name: String (1-32 characters), Required. Account name, helps users with several accounts remember which they are currently using. Displayed to the user above the "Edit/Publish" button on Telegra.ph, other users don't see this name.
  author_name: String (0-128 characters). Default author name used when creating new articles.
  author_url: String (0-512 characters). Default profile link, opened when users click on the author's name below the title. Can be any link, not necessarily to a Telegram profile or channel.

Sample request: https://api.telegra.ph/createAccount?short_name=Sandbox&author_name=Anonymous
```

--------------------------------

### JavaScript DOM to Telegraph API Content Conversion and Page Creation

Source: https://telegra.ph/api/index

This JavaScript code provides utility functions to convert between standard browser DOM nodes and the Telegraph API's specific DOM-based content format. It includes `domToNode` for converting DOM to API format and `nodeToDom` for converting API format back to DOM. Additionally, it demonstrates how to use the converted content to create a new page on the Telegraph platform using an AJAX POST request to the `/createPage` endpoint, including handling the response to update the page content.

```javascript
function domToNode(domNode) {
  if (domNode.nodeType == domNode.TEXT_NODE) {
    return domNode.data;
  }
  if (domNode.nodeType != domNode.ELEMENT_NODE) {
    return false;
  }
  var nodeElement = {};
  nodeElement.tag = domNode.tagName.toLowerCase();
  for (var i = 0; i < domNode.attributes.length; i++) {
    var attr = domNode.attributes[i];
    if (attr.name == 'href' || attr.name == 'src') {
      if (!nodeElement.attrs) {
        nodeElement.attrs = {};
      }
      nodeElement.attrs[attr.name] = attr.value;
    }
  }
  if (domNode.childNodes.length > 0) {
    nodeElement.children = [];
    for (var i = 0; i < domNode.childNodes.length; i++) {
      var child = domNode.childNodes[i];
      nodeElement.children.push(domToNode(child));
    }
  }
  return nodeElement;
}

function nodeToDom(node) {
  if (typeof node === 'string' || node instanceof String) {
    return document.createTextNode(node);
  }
  if (node.tag) {
    var domNode = document.createElement(node.tag);
    if (node.attrs) {
      for (var name in node.attrs) {
        var value = node.attrs[name];
        domNode.setAttribute(name, value);
      }
    }
  } else {
    var domNode = document.createDocumentFragment();
  }
  if (node.children) {
    for (var i = 0; i < node.children.length; i++) {
      var child = node.children[i];
      domNode.appendChild(nodeToDom(child));
    }
  }
  return domNode;
}

var article = document.getElementById('article');
var content = domToNode(article).children;
$.ajax('https://api.telegra.ph/createPage', {
  data: {
    access_token:   '%access_token%',
    title:           'Title of page',
    content:        JSON.stringify(content),
    return_content: true
  },
  type: 'POST',
  dataType: 'json',
  success: function(data) {
    if (data.content) {
      while (article.firstChild) {
        article.removeChild(article.firstChild);
      }
      article.appendChild(nodeToDom({children: data.content}));
    }
  }
});
```

--------------------------------

### Edit Page API Method

Source: https://telegra.ph/api/index

Use this method to edit an existing Telegraph page. On success, returns a Page object.

```APIDOC
editPage:
  Description: Edits an existing Telegraph page.
  Parameters:
    access_token: String - Required. Access token of the Telegraph account.
    path: String - Required. Path to the page.
    title: String (1-256 characters) - Required. Page title.
    content: Array of Node (up to 64 KB) - Required. Content of the page.
    author_name: String (0-128 characters) - Author name, displayed below the article's title.
    author_url: String (0-512 characters) - Profile link, opened when users click on the author's name below the title. Can be any link, not necessarily to a Telegram profile or channel.
    return_content: Boolean (default = false) - If true, a content field will be returned in the Page object.
  Returns: Page object.
  Sample Request: https://api.telegra.ph/editPage/Sample-Page-12-15?access_token=d3b25feccb89e508a9114afb82aa421fe2a9712b963b387cc5ad71e58722&title=Sample+Page&author_name=Anonymous&content=[{\"tag\":\"p\",\"children\":[\"Hello,+world!\"]}]&return_content=true
```

--------------------------------

### Telegraph API: Data Types

Source: https://telegra.ph/api/index

Definitions of all JSON objects used in Telegraph API responses, including Account, PageList, Page, PageViews, Node, and NodeElement. Optional fields may not be returned when irrelevant.

```APIDOC
Account:
  Description: This object represents a Telegraph account.
  Properties:
    short_name (String): Account name, helps users with several accounts remember which they are currently using. Displayed to the user above the "Edit/Publish" button on Telegra.ph, other users don't see this name.
    author_name (String): Default author name used when creating new articles.
    author_url (String): Profile link, opened when users click on the author's name below the title. Can be any link, not necessarily to a Telegram profile or channel.
    access_token (String): Optional. Only returned by the createAccount and revokeAccessToken method. Access token of the Telegraph account.
    auth_url (String): Optional. URL to authorize a browser on telegra.ph and connect it to a Telegraph account. This URL is valid for only one use and for 5 minutes only.
    page_count (Integer): Optional. Number of pages belonging to the Telegraph account.

PageList:
  Description: This object represents a list of Telegraph articles belonging to an account. Most recently created articles first.
  Properties:
    total_count (Integer): Total number of pages belonging to the target Telegraph account.
    pages (Array of Page): Requested pages of the target Telegraph account.

Page:
  Description: This object represents a page on Telegraph.
  Properties:
    path (String): Path to the page.
    url (String): URL of the page.
    title (String): Title of the page.
    description (String): Description of the page.
    author_name (String): Optional. Name of the author, displayed below the title.
    author_url (String): Optional. Profile link, opened when users click on the author's name below the title. Can be any link, not necessarily to a Telegram profile or channel.
    image_url (String): Optional. Image URL of the page.
    content (Array of Node): Optional. Content of the page.
    views (Integer): Number of page views for the page.
    can_edit (Boolean): Optional. Only returned if access_token passed. True, if the target Telegraph account can edit the page.

PageViews:
  Description: This object represents the number of page views for a Telegraph article.
  Properties:
    views (Integer): Number of page views for the target page.

Node:
  Description: This abstract object represents a DOM Node. It can be a String which represents a DOM text node or a NodeElement object.

NodeElement:
  Description: This object represents a DOM element node.
  Properties:
    tag (String): Name of the DOM element. Available tags: a, aside, b, blockquote, br, code, em, figcaption, figure, h3, h4, hr, i, iframe, img, li, ol, p, pre, s, strong, u, ul, video.
    attrs (Object): Optional. Attributes of the DOM element. Key of object represents name of attribute, value represents value of attribute. Available attributes: href, src.
    children (Array of Node): Optional. List of child nodes for the DOM element.
```

--------------------------------

### Telegraph API: getViews Method

Source: https://telegra.ph/api/index

Method to retrieve the number of views for a Telegraph article. It supports filtering by year, month, day, and hour. Returns a PageViews object on success.

```APIDOC
getViews
  Description: Use this method to get the number of views for a Telegraph article. Returns a PageViews object on success. By default, the total number of page views will be returned.
  Parameters:
    path (String): Required. Path to the Telegraph page (in the format `Title-12-31`, where 12 is the month and 31 the day the article was first published).
    year (Integer, 2000-2100): Required if month is passed. If passed, the number of page views for the requested year will be returned.
    month (Integer, 1-12): Required if day is passed. If passed, the number of page views for the requested month will be returned.
    day (Integer, 1-31): Required if hour is passed. If passed, the number of page views for the requested day will be returned.
    hour (Integer, 0-24): If passed, the number of page views for the requested hour will be returned.
  Sample Request: https://api.telegra.ph/getViews/Sample-Page-12-15?year=2016&month=12
```

--------------------------------

### Telegraph API: Edit Account Information

Source: https://telegra.ph/api/index

This method updates existing information for a Telegraph account. Only parameters intended for modification need to be passed. A successful update returns an Account object with the modified fields.

```APIDOC
Method: editAccountInfo
Description: Use this method to update information about a Telegraph account.
Returns: Account object with the default fields.

Parameters:
  access_token: String, Required. Access token of the Telegraph account.
  short_name: String (1-32 characters). New account name.
  author_name: String (0-128 characters). New default author name used when creating new articles.
  author_url: String (0-512 characters). New default profile link, opened when users click on the author's name below the title. Can be any link, not necessarily to a Telegram profile or channel.

Sample request: https://api.telegra.ph/editAccountInfo?access_token=d3b25feccb89e508a9114afb82aa421fe2a9712b963b387cc5ad71e58722&short_name=Sandbox&author_name=Anonymous
```
Tokens:
Raw