How do I connect my own website system with Custom API?

If your website is not on WordPress, Shopify, Wix, Webflow or Strapi, but has its own JSON API for posts, use Custom API in Project settings. Paste the address that lists your posts and its token if it needs one, press Scan API, confirm which of your fields each part of a post goes into, then connect. Nothing is written until you have confirmed the mapping.

This is usually a job for whoever built your website.

#What your API needs

• An address that lists your posts: a GET request that returns JSON.
• The same address must accept new posts, and posts must be removable again.
• Each entry must have an id. Without one, posts could never be updated or removed, so connecting is blocked: we never publish where we cannot undo.
• Sign-in by a token, or none. A system that only signs in through OAuth needs one of the built-in connections instead.

#Connect it

1. On the Projects screen, press the cog on the project to open Project settings.
2. On the Connections tab, find Custom API and press Connect.
3. Fill in Posts endpoint URL, for example https://yoursite.com/api/posts.
4. Fill in API token (leave blank if the API is open).
5. Press Scan API. We read one entry and say how many we found and how your API signs in.
6. Check the proposed mapping. For each part of a post (Title, Body, Excerpt / description and Slug), choose which of your fields it goes into, or not sent to skip it. A title is required; the rest are optional. Each field shows a sample of what is in it now.
7. Press Connect Custom API.

#How publishing works on a custom API

• Posts are created however your API creates them. There is no draft setting; if your system wants drafts, it decides that itself.
• There is no unpublish. To take a post down, use Remove from CMS, which deletes the entry.
• Every publish and removal is logged in Publishing activity. See publishing connections and activity.

Title and description changes from Opportunities stay copy-and-paste on a custom API.

#Questions people ask

#The scan says the entries have no id. What now?

Your API needs to return an id for each post, so we can update or remove what we publish. Ask your developer to add one, then press Scan again.

#It says "Could not scan that API".

Check the address returns JSON when opened with the token, and that the token is right. An address that needs you to be signed in through a browser will not work.

#Can I change the mapping later?

Press Disconnect, then connect again and choose the new mapping.

#Is my token safe?

It is encrypted before it is stored and is never shown again. See account security.