<% title "DEV API" %>

<%= content_for :page_meta do %>
  <link rel="canonical" href="https://dev.to/api" />
  <meta name="description" content="<%= ApplicationConfig["COMMUNITY_NAME"] %> API info and guides">
  <meta name="keywords" content="software development,engineering,rails,javascript,ruby,security">

  <meta property="og:type" content="article" />
  <meta property="og:url" content="https://dev.to/api" />
  <meta property="og:title" content="<%= ApplicationConfig["COMMUNITY_NAME"] %> API" />

  <meta name="twitter:card" content="summary_large_image">
  <meta name="twitter:site" content="@<%= ApplicationConfig["SITE_TWITTER_HANDLE"] %>">
  <meta name="twitter:title" content="<%= ApplicationConfig["COMMUNITY_NAME"] %> API">

  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.16.0/themes/prism-tomorrow.css" integrity="sha256-0dkohC9ZEupqWbq0hS5cVR4QQXJ+mp6N2oJyuks6gt0=" crossorigin="anonymous" />  <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.16.0/prism.min.js"
        integrity="sha256-NFZVyNmS1YlmiklazBA+TALYJlJtZj/y/i/oADk6CVE=" crossorigin="anonymous" defer></script>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.16.0/components/prism-bash.min.js"
          integrity="sha256-0W9ddRPtgrjvZVUxGhU/ShLxFi3WGNV2T7A7bBTuDWo=" crossorigin="anonymous"></script>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.16.0/components/prism-json.min.js"
          integrity="sha256-18m89UBQcWGjPHHo64UD+sQx4SpMxiRI1F0MbefKXWw=" crossorigin="anonymous" defer></script>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.16.0/components/prism-markdown.min.js"
          integrity="sha256-e4izlzFmEQlenZQnzkYK5oyxV5mX6lwVQjL6onkHiy0=" crossorigin="anonymous"></script>
<% end %>

<div class="blank-space"></div>

<div class="container article">
  <div class="title">
    <h1>
      DEV Articles API (beta)
    </h1>

    <h3>
      As of May 16th 2019 DEV has released a beta version of a REST API to create or update articles.
      Check back to this page for all updates related to the API.
    </h3>
  </div>

  <div class="body">
  <div class="body" style="width: 90%;">
  <h2>
    <a name="getting-an-access-token" href="#getting-an-access-token" class="anchor">
    </a>
    About the Articles API
  </h2>
  <p>
    "Articles" are all the posts that users create on DEV that typically show up in the feed.
    They can be a blog post, a discussion question, a help thread etc. but is referred to as
    <code>article</code> within the code.
    They are different from <a href="/listings">listings</a>, comments, podcasts, etc.
  </p>

  <h2>
    <a name="getting-an-access-token" href="#getting-an-access-token" class="anchor">
    </a>
    Getting an access token
  </h2>

  <p>Authentication for the Articles API requires the <em>DEV API access token.</em> To obtain one, please follow these steps:</p>

  <ul>
  <li>Connect to <a href="https://dev.to/settings/account">https://dev.to/settings/account</a>
  </li>
  <li>
  <p>In the <strong>DEV API Access Tokens</strong> section create a new token by adding a description and clicking on "Generate Token":</p>

  <p></p>
  <p>
    <img src="https://res.cloudinary.com/practicaldev/image/fetch/s--F4Ya4WgC--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_880/https://thepracticaldev.s3.amazonaws.com/i/4zm0cbutj9o9eau0jm9t.png" alt="DEV Access tokens page" loading="lazy">
  </p>
  </li>

  <li><p>You'll see the newly generated token in the same view:</p></li>
  </ul>

  <p>
    <img src="https://res.cloudinary.com/practicaldev/image/fetch/s--kp5L6-9G--/c_limit%2Cf_auto%2Cfl_progressive%2Cq_auto%2Cw_880/https://thepracticaldev.s3.amazonaws.com/i/ra01mo6fp1es261db2ho.png" alt="DEV access tokens page with a generated token" loading="lazy">
  </p>

  <h2>
    <a name="creating-an-article-through-the-api" href="#creating-an-article-through-the-api" class="anchor">
    </a>
    Creating an article through the API
  </h2>

  <p>Here is an example of how to create an article:</p>

  <div class="highlight">
    <pre class="highlight"><code class="language-bash">curl -X POST -H "Content-Type: application/json" \
-H "api-key: ACCESS_TOKEN" \
-d '{"article": {"title": "Title", "body_markdown": "Body", "published": false, "tags": ["discuss", "javascript"]}}' \
https://dev.to/api/articles</code></pre></div>

  <p>If <code>published</code> is set to <code>true</code> then the article will be live instantly.</p>

  <h3>
    <a name="successful-response" href="#successful-response" class="anchor">
    </a>
    Successful response
  </h3>

  <p>In case of a successful response (HTTP 201), the full article resource will be returned to the client:</p>

  <div class="highlight"><pre class="highlight plaintext"><code class="language-json">{
  "type_of": "article",
  "id": 110878,
  "title": "Title",
  "description": "Body\n\n...",
  "cover_image": null,
  "readable_publish_date": null,
  "social_image": "http://dev.to/social_previews/article/110878.png",
  "tag_list": "discuss, javascript",
  "tags": [
    "discuss",
    "javascript"
  ],
  "slug": "title-2bp3-temp-slug-5875367",
  "path": "/rhymes/title-2bp3-temp-slug-5875367",
  "url": "https://dev.to/rhymes/title-2bp3-temp-slug-5875367",
  "canonical_url": "https://dev.to/rhymes/title-2bp3-temp-slug-5875367",
  "comments_count": 0,
  "positive_reactions_count": 0,
  "created_at": "2019-05-21T13:34:26Z",
  "edited_at": null,
  "crossposted_at": null,
  "published_at": null,
  "last_comment_at": "2017-01-01T05:00:00Z",
  "body_html": "&lt;p&gt;Body&lt;/p&gt;\n\n",
  "ltag_style": [],
  "ltag_script": [],
  "user": {
    "name": "rhymes",
    "username": "rhymes",
    "twitter_username": "rhymes_",
    "github_username": "rhymes",
    "website_url": null,
    "profile_image": "https://res.cloudinary.com/practicaldev/image/fetch/s--qhCNe-v6--/c_fill,f_auto,fl_progressive,h_640,q_auto,w_640/https://thepracticaldev.s3.amazonaws.com/uploads/user/profile_image/2693/146201.jpeg",
    "profile_image_90": "https://res.cloudinary.com/practicaldev/image/fetch/s--IQPhTQnb--/c_fill,f_auto,fl_progressive,h_90,q_auto,w_90/https://thepracticaldev.s3.amazonaws.com/uploads/user/profile_image/2693/146201.jpeg"
  }
}</code></pre></div>
  <h3>
    <a name="create-an-article-on-behalf-an-organisation" href="#create-an-article-on-behalf-an-organisation" class="anchor">
    </a>
    Create an article on behalf an organisation
  </h3>

  <p>Just add <code>publish_under_org</code> as <code>true</code> to the JSON request:</p>
  <div class="highlight"><pre class="highlight plaintext"><code class="language-bash">curl -X POST -H "Content-Type: application/json" \
-H "api-key: ACCESS_TOKEN" \
-d '{"article": {"title": "Title", "body_markdown": "Body", "published": false, "publish_under_org": true}}' \
https://dev.to/api/articles</code></pre></div>
  <h3>
    <a name="using-the-front-matter" href="#using-the-front-matter" class="anchor">
    </a>
    Using the front matter
  </h3>

  <p>You can omit most JSON parameters by using the markdown front matter. So for example, if you have markdown article similar to the following:</p>
  <div class="highlight"><pre class="highlight plaintext"><code class="language-markdown">---
title: "A sample article about JavaScript"
published: false
description: "this is a sample article about javascript"
tags: discuss, javascript
series: intro-to-javascript
canonical_url: canonical URL of the article
---

This is an intro about JavaScript</code></pre></div>

  <p>you can send it within the <code>body_markdown</code> parameter:</p>

  <div class="highlight"><pre class="highlight plaintext"><code class="language-bash">curl -X POST -H "Content-Type: application/json" \
-H "api-key: ACCESS_TOKEN" \
-d '{"article": {"body_markdown": "---\ntitle: A sample article about...\npublished: false\n...", "publish_under_org": true}}' \
https://dev.to/api/articles</code></pre></div>

  <p>The front matter will take precedence on other JSON params with the same name.</p>

  <h3>
    <a name="available-json-parameters" href="#available-json-parameters" class="anchor">
    </a>
    Available JSON parameters
  </h3>

  <div class="highlight"><pre class="highlight plaintext"><code>title: The title of an article (string, optional)
description: Description of the article (string, optional)
body_markdown: The Markdown body, with or without a front matter (string, required)
published: True if the article should be published right away, defaults to false (boolean, optional)
tags: A list of tags for the article (array, optional)
series: The name of the series the article should be published within (string, optional)
publish_under_org: True if the article should be placed under the organization belonging to the user creating the article, defaults to false (boolean, optional)
main_image: URL of the image to use as the cover (string, optional)
canonical_url: canonical URL of the article (string, optional)</code></pre></div>
  <h3>
    <a name="error-responses" href="#error-responses" class="anchor">
    </a>
    Error responses
  </h3>

  <p><strong>Unauthorized</strong></p>
  <div class="highlight"><pre class="highlight plaintext"><code class="language-json">{
  "error": "unauthorized",
  "status": 401
}</code></pre></div>

  <p><strong>Parameter validation error</strong></p>

  <div class="highlight"><pre class="highlight plaintext"><code class="language-json">{
  "error": "Validation failed: Title can't be blank",
  "status": 422
}</code></pre></div>

  <h2>
    <a name="updating-an-article-through-the-api" href="#updating-an-article-through-the-api" class="anchor">
    </a>
    Updating an article through the API
  </h2>

  <p>Here is an example of how to update an article:</p>
  <div class="highlight"><pre class="highlight plaintext"><code class="language-shell">curl -X PUT -H "Content-Type: application/json" \
-H "api-key: ACCESS_TOKEN" \
-d '{"article": {"title": "New Title"}}' \
https://dev.to/api/articles/ARTICLE_ID</code></pre></div>

  <h3>
    <a name="successful-response" href="#successful-response" class="anchor">
    </a>
    Successful response
  </h3>

  <p>In case of a successful response (HTTP 200), the full article resource will be returned to the client:</p>
  <div class="highlight"><pre class="highlight plaintext"><code class="language-json">{
  "type_of": "article",
  "id": 110878,
  "title": "New Title",
  "description": "Body\n\n...",
  "cover_image": null,
  "readable_publish_date": null,
  "social_image": "http://dev.to/social_previews/article/110878.png",
  "tag_list": "discuss, javascript",
  "tags": [
    "discuss",
    "javascript"
  ],
  "slug": "title-2bp3-temp-slug-5875367",
  "path": "/rhymes/title-2bp3-temp-slug-5875367",
  "url": "https://dev.to/rhymes/title-2bp3-temp-slug-5875367",
  "canonical_url": "https://dev.to/rhymes/title-2bp3-temp-slug-5875367",
  "comments_count": 0,
  "positive_reactions_count": 0,
  "created_at": "2019-05-21T13:34:26Z",
  "edited_at": null,
  "crossposted_at": null,
  "published_at": null,
  "last_comment_at": "2017-01-01T05:00:00Z",
  "body_html": "&lt;p&gt;Body&lt;/p&gt;\n\n",
  "ltag_style": [],
  "ltag_script": [],
  "user": {
    "name": "rhymes",
    "username": "rhymes",
    "twitter_username": "rhymes_",
    "github_username": "rhymes",
    "website_url": null,
    "profile_image": "https://res.cloudinary.com/practicaldev/image/fetch/s--qhCNe-v6--/c_fill,f_auto,fl_progressive,h_640,q_auto,w_640/https://thepracticaldev.s3.amazonaws.com/uploads/user/profile_image/2693/146201.jpeg",
    "profile_image_90": "https://res.cloudinary.com/practicaldev/image/fetch/s--IQPhTQnb--/c_fill,f_auto,fl_progressive,h_90,q_auto,w_90/https://thepracticaldev.s3.amazonaws.com/uploads/user/profile_image/2693/146201.jpeg"
  }
}</code></pre></div>

  <h3>
    <a name="notes-about-the-front-matter-during-an-update" href="#notes-about-the-front-matter-during-an-update" class="anchor">
    </a>
    Notes about the front matter during an update
  </h3>

  <p>Keep in mind that if the original article was created with the front matter in the markdown then that front matter will still take precedence over the partial updates. So if you need to change parameters present in the front matter, you should send the whole edited body (with the front matter parameter changed) in the <code>body_markdown</code> parameter.</p>
  <h3>
    <a name="available-json-parameters" href="#available-json-parameters" class="anchor">
    </a>
    Available JSON parameters
  </h3>
  <div class="highlight"><pre class="highlight plaintext"><code>title: The title of an article (optional)
description: Description of the article (optional)
body_markdown: The Markdown body, with or without a front matter (required)
published: True if the article should be published right away, defaults to false (optional)
series: The name of the series the article should be published within (optional)
publish_under_org: True if the article should be placed under the organization belonging to the user creating the article, defaults to false (optional)
main_image: URL of the image to use as the cover (optional)
canonical_url: canonical URL of the article (optional)</code></pre></div>
  <h3>
    <a name="error-responses" href="#error-responses" class="anchor">
    </a>
    Error responses
  </h3>

  <p><strong>Unauthorized</strong></p>
  <div class="highlight"><pre class="highlight plaintext"><code class="language-json">{
  "error": "unauthorized",
  "status": 401
}</code></pre></div>

  <p><strong>Parameter validation error</strong></p>

  <div class="highlight"><pre class="highlight plaintext"><code class="language-json">{
  "error": "Validation failed: Title can't be blank",
  "status": 422
}</code></pre></div>
  <h2>
    <a name="rate-limiting" href="#rate-limiting" class="anchor">
    </a>
    Rate limiting
  </h2>

  <p>There is a limit of 10 articles created each 30 seconds by the same user. </p>

  <p>There are no limits on the updates.</p>

  <h2>
    <a name="additional-resources" href="#additional-resources" class="anchor">
    </a>
    Additional resources
  </h2>

  <ul>
  <li><a href="https://github.com/thepracticaldev/dev.to/blob/master/spec/requests/api/v0/articles_spec.rb">Rails tests for the Articles API</a></li>
  </ul>

  </div>
</div>
</div>
