Contesimal

wondermentapps

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

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.

External services and privacy

<ul>
<li>Service: Designed to work with Contesimal (https://contesimal.ai), but compatible with any client using your API key.</li>
<li>Data received: 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>Media handling: Your WordPress site may download remote files from provided URLs to create Media Library attachments.</li>
<li>When: Only when a valid API request is sent to your site. No background communication occurs.</li>
<li>Control: 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>Consent: By enabling the plugin and sharing the API key, the site administrator allows external applications to submit content.</li>
</ul>

Authentication

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

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

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

API keys should be treated as sensitive credentials and only shared with trusted systems.

Features

<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>

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

<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>

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

<h3>REST API Reference</h3>

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

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

Returns plugin status.

Response:
{ “status”: “ok”, “plugin”: “contesimal-connector”, “version”: “1.0.0” }

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

Returns category list.

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

Returns public post types.

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

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

Query parameters (all optional):




 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)




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

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

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

Query parameters (all optional):




 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




Response (example):
{ “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”: “

Hello

” } ] }

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

Creates a post.

Headers:
Content-Type: application/json 
X-API-Key: your_api_key

Body:




 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




Responses:
– 200 Success
– 400 Bad request
– 401 Invalid API key
– 429 Rate limit exceeded
– 500 Server error

Contesimal Connector

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

Kal Ström

henrikmelin

This is an early beta – fixes and better documentation to come. Promise.

More Taxonomies

Add more taxonomies to your WordPress installation.

Contesimal Connector vs More Taxonomies