Fields

NameTypeDescriptionUser-specified?Required?Default valuePossible valuesMaximum length
idintegerSystem-generated identifier.NoYes---
orderintegerUsed to sort article when displayed.YesYes999--
titlestringTitle of article derived from the default translation.YesNo--255
authorobjectOriginal author or creator of article. When creating a new article, defaults to owner of the JWT.NoYes---
sourcestringOriginal source of article.NoYesapiapi, custom, zendesk, freshdesk, helpscout, wordpress25
external_idstringArticle identifier in the source system.YesNo--255
editor_versionstringVersion of article editor used to create this article.NoYes21, 210
notesstringInternal notes for contributors.YesNo---
keywordsstring arrayList of keywords for tagging and discoverability.YesNo---
category_idintegerIdentifier of category to which the article belongs.YesYes-Has to correspond to a valid category.-
accessstringLevel of access granted for this article.YesYespublicpublic, restricted, none10
access_emails (deprecated)string arrayList of emails for users permitted to access this article when access is restricted.YesNo---
access_domains (deprecated)string arrayList of Internet domains from which this article can be accessed when access is restricted.YesNo---
access_groups (deprecated)string arrayList of groups for users permitted to access this article when access is restricted.YesNo---
smart_groupsobject arrayList of smart groups that apply to this articleYesNo---
statusstringStatus of articleYesYespublisheddraft, published50
last_publisherobjectUser who last published this article. When publishing, defaults to owner of the JWT.NoNo---
last_published_attimestampUTC timestamp of when the article was last published.NoNoRequest date--
contributorsobject arrayList of users who contributed edits to this article.NoYes---
created_attimestampUTC timestamp of when the article was first created.NoYesRequest date--
updated_attimestampUTC timestamp of when the article was last modified.NoYesRequest date--
translationsobject arrayList of available translations in supported languages.YesYes---
translation.language_idstringISO 639-1 language code of the translation.YesYesenSee list of supported languages-
translation.titlestringTitle of article.YesNo--255
translation.bodystringContent of article.YesNo---
translation.summarystringUser-specified summary of article.YesNo---
translation.machine_summarystringMachine-generated summary of article.NoNo---

Methods

List all articles
  • GET: curl https://api.elev.io/v1/articles?page=<page>&status=<status>
  • Optional query string parameters:
    • Pagination
      • page: Current page
      • page_size: Page size. Defaults to 100. Max size is 500.
    • status
      • draft to retrieve only drafts
      • published to retrieve only published
    • from_created_at and to_created_at: Filter by creation date range in epoch milliseconds
    • from_published_at and to_published_at: Filter by publish date range in epoch milliseconds
  • Sample JSON response body:
 {
    "articles": [
      {
        "id": 42,
        "order": 1,
        "title": "Make placeholder title great again",
        "source": "api",
        "external_id": "42",
        "editor_version": "2",
        "notes": "Make placeholder note great again",
        "keywords": ["welcome", "article", "onboarding"],
        "category_id": 66,
        "category_groups": [],
        "subcategory_groups": [],
        "article_groups": [],
        "smart_groups": [
          {"id": 42, "name": "authenticated"}, 
          {"id": 43, "name": "beta_users"}
        ],
        "access": "restricted",
        "access_emails": ["hiro@example.com", "satoshi@example.com"],
        "access_domains": ["example.com", "elev.io"],
        "status": "published",
        "updated_at": "2017-09-20T02:49:00.000000Z",
        "translations": [
          {
            "id": 1,
            "title": "Make placeholder title great again",
            "language_id": "en",
            "updated_at": "2017-09-20T02:49:00.000000Z"
          }
        ]
      }
    ],
    "page_number": 1,
    "page_size": 100,
    "total_pages": 1,
    "total_entries": 1
  }
Get a single article
  • GET: curl -X GET https://api.elev.io/v1/articles/<id>
  • Sample JSON response body:
 {
    "article": {
      "id": 42,
      "title": "Make placeholder title great again",
      "author": {
        "id": 66,
        "name": "Hiro Protagonist",
        "gravatar": "https://www.gravatar.com/avatar/db9cb821290bb38c4ef7a93bccb81b4e",
        "email": "hiro@example.com"
      },
      "source": "api",
      "external_id": "42",
      "order": 1,
      "category_id": 66,
      "access": "restricted",
      "access_emails": [],
      "access_domains": [],
      "access_groups": [],
      "smart_groups": [
        {"id": 42, "name": "authenticated"}, 
        {"id": 43, "name": "beta_users"}
      ],
      "keywords": ["welcome", "article", "onboarding"],
      "notes": "Make placeholder note great again",
      "status": "published",
      "last_publisher": {
        "id": 66,
        "name": "Hiro Protagonist",
        "gravatar": "https://www.gravatar.com/avatar/db9cb821290bb38c4ef7a93bccb81b4e",
        "email": "hiro@example.com"
      },
      "last_published_at": "2017-09-29T02:49:00.000000Z",
      "contributors": [
        {
          "id": 66,
          "name": "Hiro Protagonist",
          "gravatar": "https://www.gravatar.com/avatar/db9cb821290bb38c4ef7a93bccb81b4e",
          "email": "hiro@example.com"
        }
      ],
      "editor_version": "2",
      "created_at": "2015-12-16T02:02:04.000000Z",
      "updated_at": "2017-09-20T02:49:00.000000Z",
      "translations": [
        {
          "id": 1,
          "title": "Make placeholder title great again",
          "body": "Make placeholder body great again",
          "summary": "Make placeholder summary great again",
          "machine_summary": "Make placeholder machine summary great again",
          "language_id": "en",
          "created_at": "2014-08-30T05:57:43.000000Z",
          "updated_at": "2017-06-01T02:07:15.113612Z"
        },
        {
          "id": 2,
          "title": "Willkommensartikel",
          "body": "Dies ist der tatsächliche Inhalt des Artikels",
          "summary": "Willkommensartikel für neue Mitarbeiter",
          "machine_summary": "Willkommensartikel für neue Mitarbeiter",
          "language_id": "de",
          "created_at": "2014-08-30T05:57:43.000000Z",
          "updated_at": "2017-06-01T02:07:15.113612Z"
        }
      ]
    }
  }
Create a new article
  • POST: curl -H "Content-Type: application/json" -X POST --data @body.json https://api.elev.io/v1/articles
  • Sample request body:
 {
    "article": {
      "external_id": "42",
      "order": 1,
      "category_id": 42,
      "access": "restricted",
      "smart_groups": [{"id": 42}],
      "keywords": ["welcome", "article"],
      "notes": "Make placeholder note great again",
      "status": "published",
      "translations": [
        {
          "language_id": "en",
          "title": "Make placeholder title great again",
          "body": "Make placeholder body great again"
        }
      ]
    }
  }
NB: Please note you can only create one article at a time.
Update an existing article
  • PUT: curl -H "Content-Type: application/json" -X PUT --data @body.json https://api.elev.io/v1/articles/<id>
  • Sample request body:
 {
    "article": {
      "id": 42,
      "external_id": "42",
      "order": 2,
      "category_id": 43,
      "access": "restricted",
      "smart_groups": [{"id": 43}],
      "keywords": ["welcome", "article"],
      "notes": "Make placeholder note great again",
      "status": "published",
      "translations": [
        {
          "id": 66,
          "language_id": "en",
          "title": "Make placeholder title great again",
          "body": "Make placeholder body great again"
        }
      ]
    }
  }

NB: Please note you can only update one article at a time.

Delete an article
  • DELETE: curl -X DELETE https://api.elev.io/v1/articles/<id>