API Reference

Complete reference for all Simple Product API endpoints.

Base URL

https://simpleproduct.dev/api/v1

Authentication

All API requests require authentication via API key (except public endpoints):

Authorization: Bearer YOUR_API_KEY

Get your API key from Settings → API Keys in your workspace.

Feedback

POST

/api/v1/feedback

Submit customer feedback.

Request Body

{ "title": "Feature request", "content": "I would love to see...", "email": "customer@example.com", "name": "John Doe", "source": "widget", "metadata": { "page": "/settings" } }

Field	Type	Required	Description
title	string	Yes	Feedback title
content	string	Yes	The feedback message
email	string	No	Customer email
name	string	No	Customer name
externalId	string	No	Your user ID
source	string	No	Feedback source
metadata	object	No	Custom JSON data

People (Customers)

POST

/api/v1/people

Create or update a customer record.

Request Body

{ "email": "customer@example.com", "name": "John Doe", "externalId": "user_123", "properties": { "plan": "pro", "company": "Acme Inc" } }

GET

/api/v1/people?email=customer@example.com

Look up a customer by email.

GET

/api/v1/people/:id

Get a customer by ID.

Organizations

POST

/api/v1/organizations

Create or update an organization.

Request Body

{ "name": "Acme Inc", "domain": "acme.com", "properties": { "plan": "enterprise", "seats": 50 } }

Import (CSV)

POST

/api/v1/imports

Import cards from a CSV, such as a Shortcut, Linear, Jira or Trello export, onto a new board that mirrors the old tool. Its stages are the export's states in workflow order, each row becomes a card in its stage, and every other column goes at the bottom of the card's description. Imported cards don't fire card.created, so skills and webhooks stay quiet. To undo an import, delete the board.

Send the file as the body with Content-Type: text/csv, or as JSON ({ "csv": "...", "fileName": "...", "boardName": "..." }). The board is named after the tool ("Shortcut import") unless you pass boardName. Up to 5,000 rows and 5MB.

Example

curl -X POST "https://simpleproduct.dev/api/v1/imports?fileName=stories.csv" \ -H "Authorization: Bearer sk_ws_..." \ -H "Content-Type: text/csv" \ --data-binary @stories.csv

Response

{ "data": { "boardId": "...", "boardName": "Shortcut import", "source": "Shortcut", "created": 42, "skipped": 1, "stages": [ { "name": "Unscheduled", "count": 10 }, { "name": "Ready for Development", "count": 9 }, ... ], "link": "/app/your-workspace/boards/..." } }

Releases (Changelog)

GET

/api/v1/releases/public?workspace=YOUR_WORKSPACE_SLUG

Get published releases, newest first. No authentication required.

Paginated: limit (1–100, default 20) and cursor (the previous page's meta.nextCursor). The response's meta has count, nextCursor and hasMore. The same parameters work on /api/v1/docs/public. Responses are cacheable (60s, with an ETag).

POST

/api/v1/releases

Create a new release.

Request Body

{ "title": "v2.1.0", "content": "## What's New\n- Dark mode\n- Bug fixes", "status": "published", "publishedAt": 1234567890 }

Events (Analytics)

POST

/api/v1/events

Track a custom event.

Request Body

{ "event": "feature_used", "email": "customer@example.com", "externalId": "user_123", "properties": { "feature": "export", "format": "csv" } }

Error Responses

All errors return JSON with an error message:

{ "error": "Error message here" }

Status Codes

Code	Description
400	Bad request (missing/invalid fields)
401	Unauthorized (missing/invalid API key)
404	Not found
429	Rate limited
500	Server error