API Reference

The OpenPuzzle API lets vendors manage solutions and articles programmatically, and lets anyone read published content from the marketplace.

Authentication

Write endpoints accept either of two credentials:

Browser session — a vendor signed in at openpuzzle.ai (session cookie is sent automatically).
API key — send an Authorization: Bearer <key> header. Generate and revoke keys from the Vendor Portal → API Keys page.

Requests without valid credentials return 401 Unauthorized. Operating on another vendor's resource returns 403 Forbidden.

Solutions

GET/api/solutions/No auth required

List all published solutions.

GET/api/solutions/{id}/No auth required

Get a single solution. {id} accepts either the solution id or its slug. Returns 404 if not found.

POST/api/solutions/Vendor session or API key

Create a solution for the authenticated vendor. Required JSON body fields:

{
  "title": "AI Chatbot",              // min 3 chars
  "slug": "ai-chatbot",               // min 3 chars, unique
  "shortDescription": "...",          // min 10 chars
  "description": "...",               // min 20 chars
  "problem": "...",                   // min 20 chars
  "businessOutcome": "...",           // min 20 chars
  "howToUse": "...",                  // min 20 chars
  "price": 49,
  "currency": "USD",
  "categoryId": "<category id>",
  "tags": ["<tag id>", "..."],
  "images": ["https://... or /local/path"],
  "features": ["Feature one", "..."]
}
// Optional: solutionType ("ready-made"|"customized", default "ready-made"),
//   pricingModel ("one-off"|"subscription"|"both", default "one-off"),
//   worksBestWith: ["..."], demoUrl, documentationUrl,
//   status ("draft"|"published"|"archived", default "published")

Returns the created solution with status 201. Validation errors return 400 with details.

PUT/api/solutions/{id}/Vendor session or API key

Update a solution owned by the authenticated vendor. Same fields as POST, all optional. Returns the updated solution.

DELETE/api/solutions/{id}/Vendor session or API key

Delete a solution owned by the authenticated vendor. Returns {"success": true}.

Articles (public read)

GET/api/articles/No auth required

List published articles, newest first. The article body (content) is omitted from list responses.

GET/api/articles/{slug}/No auth required

Get a single published article with full content. {slug} accepts either the slug or the article id. Draft articles return 404.

Articles (vendor write)

POST/api/vendor/articles/Vendor session or API key

Create an article for the authenticated vendor. JSON body:

{
  "title": "5 Reasons to Buy Ready-Made",  // min 3 chars
  "content": "Full article text...",        // min 20 chars
  "excerpt": "Short summary",              // optional, max 300 chars
  "coverImage": "https://.../cover.jpg",   // optional URL
  "solutionId": "<solution id>",           // optional, must be your own solution
  "status": "draft"                        // "draft" (default) or "published"
}

Returns the created article (with its generated slug) and status 201.

PUT/api/vendor/articles/{id}/Vendor session or API key

Update an article owned by the authenticated vendor. Same fields as POST, all optional. Only the owner may update; otherwise 403.

DELETE/api/vendor/articles/{id}/Vendor session or API key

Delete an article owned by the authenticated vendor. Only the owner may delete; otherwise 403.

Example

Create an article using an API key:

curl -X POST https://www.openpuzzle.ai/api/vendor/articles/ \
  -H "Authorization: Bearer opk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Getting the most from your purchase",
    "excerpt": "Tips from our team",
    "content": "Once you have installed the solution, the first thing to do is...",
    "status": "published"
  }'

Manage API Keys

Generate and revoke vendor API keys.

Browse Articles

See published vendor articles on the marketplace.