wondermentapps

Contesimal


<p>Contesimal Connector adds REST API endpoints to your WordPress site, allowing external applications to create and manage content using an API key.</p>

<p>Requests are made to your site’s <code>/wp-json/contesimal/v1/</code> endpoints. The plugin does not send any data externally on its own.</p>

<p><strong>External services and privacy</strong></p>

<ul>
<li><strong>Service:</strong> Designed to work with Contesimal (https://contesimal.ai), but compatible with any client using your API key.</li>
<li><strong>Data received:</strong> Post title, content (HTML), excerpt, status, categories, tags, post type, author ID, and media URLs. The optional users endpoint returns public-style author fields (ID, display name, slug) for users who can edit posts—no passwords or email.</li>
<li><strong>Media handling:</strong> Your WordPress site may download remote files from provided URLs to create Media Library attachments.</li>
<li><strong>When:</strong> Only when a valid API request is sent to your site. No background communication occurs.</li>
<li><strong>Control:</strong> External access is enabled only if you share the API key. You can regenerate the key or deactivate the plugin at any time.</li>
<li><strong>Consent:</strong> By enabling the plugin and sharing the API key, the site administrator allows external applications to submit content.</li>
</ul>

<p><strong>Authentication</strong></p>

<p>All endpoints require an API key sent in the <code>X-API-Key</code> header (or <code>Authorization: Bearer</code>).</p>

<p>The key is:
– Generated on your site
– Stored as a secure hash
– Managed by administrators only</p>

<p>Requests without a valid key are rejected (401). Rate limiting is applied per IP.</p>

<p>API keys should be treated as sensitive credentials and only shared with trusted systems.</p>

<p><strong>Features</strong></p>

<ul>
<li>API key authentication (hashed storage)</li>
<li>Create posts via REST API</li>
<li>List categories, post types, and author-capable users (IDs for <code>author_id</code>)</li>
<li>Media import from external URLs</li>
<li>Rate limiting (per IP)</li>
<li>Configurable CORS</li>
<li>Optional request logging (admin only)</li>
</ul>

<p><strong>REST endpoints (base: <code>/wp-json/contesimal/v1</code>)</strong></p>

<ul>
<li><code>GET /ping</code> – Health check</li>
<li><code>GET /categories</code> – List categories</li>
<li><code>GET /post-types</code> – List public post types</li>
<li><code>GET /users</code> – List users with <code>edit_posts</code> (optional <code>session_only</code>, <code>search</code>, <code>limit</code>)</li>
<li><code>GET /posts</code> – List posts by post type with pagination and total count</li>
<li><code>POST /publish</code> – Create post</li>
<li><code>POST /media/import</code> – Import media from URLs</li>
</ul>

<p>An admin notice is shown when API access is enabled, indicating that external publishing is active.</p>

<h3>REST API Reference</h3>

<p>All endpoints require: <code>X-API-Key: your_api_key</code></p>

<h4>GET /wp-json/contesimal/v1/ping</h4>

<p>Returns plugin status.</p>

<p><strong>Response:</strong>
{ “status”: “ok”, “plugin”: “contesimal-connector”, “version”: “1.0.0” }</p>

<h4>GET /wp-json/contesimal/v1/categories</h4>

<p>Returns category list.</p>

<h4>GET /wp-json/contesimal/v1/post-types</h4>

<p>Returns public post types.</p>

<h4>GET /wp-json/contesimal/v1/users</h4>

<p>Returns users who can author posts (<code>edit_posts</code>), suitable for <code>author_id</code> on <code>POST /publish</code>.</p>

<p><strong>Query parameters (all optional):</strong></p>




  Parameter
  Description




  search
  Substring match on login, nicename, or display name


  session_only
  <code>1</code> to only include users with stored WordPress session tokens (typically logged in recently)


  limit
  Max results, 1–200 (default 200)




<p><strong>Response (example):</strong>
{ “success”: true, “users”: [ { “id”: 1, “name”: “Site Admin”, “slug”: “admin” } ] }</p>

<h4>GET /wp-json/contesimal/v1/posts</h4>

<p>Returns a paginated list of posts for a given post type, plus the total count for that filter.</p>

<p><strong>Query parameters (all optional):</strong></p>




  Parameter
  Description




  post_type
  Public post type (default <code>post</code>)


  per_page
  1–100, default 50


  offset
  Number of posts to skip (default 0)


  status
  Comma-separated status list (default <code>publish</code>), or <code>any</code>


  search
  Optional keyword across title/content




<p><strong>Response (example):</strong>
{ “success”: true, “post_type”: “post”, “total”: 124, “per_page”: 50, “offset”: 0, “count”: 50, “posts”: [ { “post_id”: 42, “title”: “Hello world”, “slug”: “hello-world”, “status”: “publish”, “date”: “2026-05-14T11:50:00+00:00”, “author_name”: “Site Admin”, “link”: “https://example.com/hello-world/”, “featured_image”: “https://example.com/wp-content/uploads/2026/05/cover.jpg”, “featured_image_id”: 99, “categories”: [ “News”, “Updates” ], “tags”: [ “Announcement”, “WordPress” ], “content”: “</p>

<p class="wp-block-paragraph">Hello</p>

<p>” } ] }</p>

<h4>POST /wp-json/contesimal/v1/publish</h4>

<p>Creates a post.</p>

<p><strong>Headers:</strong>
Content-Type: application/json<br />
X-API-Key: your_api_key</p>

<p><strong>Body:</strong></p>




  Field
  Type
  Required
  Description




  title
  string
  Yes
  Post title


  content
  string
  Yes
  HTML content


  status
  string
  No
  publish, draft, pending, private


  excerpt
  string
  No
  Post excerpt


  post_type
  string
  No
  Default: post


  category_ids
  array
  No
  Category IDs


  tags
  array
  No
  Tag names


  featured_image_url
  string
  No
  Image URL


  author_id
  integer
  No
  Default: 1




<p><strong>Responses:</strong>
– 200 Success
– 400 Bad request
– 401 Invalid API key
– 429 Rate limit exceeded
– 500 Server error</p>



Contesimal Connector

Publish content to WordPress from external applications via a secure REST API using API key authentication.

Darren Grant

<p>Post Type Archive Pages allows you to select pages from within your content page structure to be the archive pages for your custom post types. This gives you control of the permalink for your archive pages and allows them to be nested under other pages. It also sets the permalink base for single posts of that post type and term archive for the post type’s taxonomies.</p>
<p>Once the plugin is installed and activated you’ll be able to select the archive page for each of your registered post types under Settings > Reading.</p>
<h3>Templating</h3>
<p>WordPress will look for archive page templates for the pages that you set as archive pages. So <em>archive-$posttype.php</em> and <em>archive.php</em> will be used rather than <em>page.php</em>.</p>
<p>There are also a few functions available that may be helpful in building themes. They are accessed on the plugin’s main instance, which is returned by a call to <em>post_type_archive_pages()</em>.</p>
<h4>get_archive_page</h4>
<p>Returns the page object for the archive page of the provided post type slug. If called from a post type archive template, a singular template or a term archive and a slug isn’t provided, the relative post type will be used. e.g.</p>
<pre><code>$page = post_type_archive_pages()->get_archive_page('book');
</code></pre>
<h4>get_archive_page_post_type</h4>
<p>Returns the post type object that the provided page ID is the archive page for. e.g.</p>
<pre><code>$postType = post_type_archive_pages()->get_archive_page_post_type(5);
</code></pre>
<h3>Menu – Enhancements</h3>
<p>Archive pages added to the menu will be marked as the current menu item when viewing the post type archive and the current menu item’s parent / ancestor when viewing a post of that type. The related CSS classes will also be applied.</p>
<h3>Advanced Custom Fields – Enhancements</h3>
<p>This plugin is particularly effective when paired with <a href="https://www.advancedcustomfields.com/" rel="nofollow ugc">Advanced Custom Fields</a>. It registers additional <em>page type</em> location rules allowing you to add fields to all archive pages or the archive page for a particular post type. So if your listing page requires content like a description or header image you can place fields for those on the archive page itself.</p>
<p>To access fields like these in your archive template you need only call</p>
<pre><code>$desc = get_field( 'description', post_type_archive_pages()->get_archive_page() );
</code></pre>
<h3>Developer Hooks</h3>
<p>The plugin attempts to set defaults that should work best for most scenarios. But there are some places to hook in and alter these defaults where needed.</p>
<h4>Filter – post_type_archive_pages/supported_post_types</h4>
<p>By default you will be able to set an archive page for any public post type other than the built in post types of <em>page</em> and <em>post</em>. This hook allows you to filter the default array of supported post types to add or remove. The array should contain slugs of valid post types. Please note that the array keys are not important in it’s use, but contain the slugs to allow you to easily unset values.</p>
<pre><code>add_filter( 'post_type_archive_pages/supported_post_types', function( $post_types ){
    unset( $post_types['book'] );
    return $post_types;
} );
</code></pre>
<h4>Filter – post_type_archive_pages/taxonomy_post_type</h4>
<p>By default taxonomy term archives will inherit the archive page permalink structure of a post type if that post type is the only one that the taxonomy is registered on. For instance if you had a <em>publisher</em> taxonomy the permalink for a term archive might become <em>/books/publisher/penguin</em>. With <em>/books</em> being the permlaink of the archive page, <em>publisher</em> the taxonomy slug and <em>penguin</em> the term slug. This filter allows you to alter the post type who’s archive page permalink structure will be inherited for a given taxonomy.</p>
<pre><code>add_filter( 'post_type_archive_pages/taxonomy_post_type', function( $post_type, $taxonomy ){
    if ( $taxonomy === 'publisher' ) return null;
    return $post_type;
}, 10, 2 );
</code></pre>


Post Type Archive Pages

Place the archive pages for your post types in the structure of your content pages. The power of pages and post types combined!

Contesimal Connector vs Post Type Archive Pages