Suggestions

Suggestions are text-first improvement proposals for workflow and context packs. Anyone who can read a pack can create one; only the author can update it, and only the pack's owner can resolve it. See Suggestions for the lifecycle and permission model.

accountId is resolved from the auth token and is never passed in the request. The active workspace comes from the token or the workspaceId query parameter. Creating a suggestion costs 5 credits; listing costs 2 credits; reading, updating, and resolving cost 1 credit each.

Create a suggestion

POST /v1/suggestions
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "reference": "@market-research",
  "title": "Add review step",
  "content": "Add a final human review before publishing."
}

reference is a pack ID, @alias, share URL, or hub URL. title and content are required. Returns 201. The pack's content at creation time is captured as a snapshot. Each account can create up to 20 suggestions per day.

List suggestions

POST /v1/suggestions/search
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "owner": true,
  "statuses": ["open"]
}

The search body mirrors the CLI flags:

• omit owner and reference to list suggestions you submitted.
• owner: true returns your inbox — suggestions on packs you own.
• reference returns suggestions for one pack (optionally narrowed by author).

statuses filters by open, applied, declined, and archived. Use page to paginate (page size 20) and includeSnapshots to include captured pack content. The response includes suggestions, totalCount, page, and pageSize.

Each suggestion's content in the list response is a truncated preview. Fetch the full content with GET /v1/suggestions/:id, mirroring the pack outline → full pattern.

Get a suggestion

curl "https://api.epismo.ai/v1/suggestions/$SUGGESTION_ID?includeSnapshot=true" \
  -H "authorization: Bearer $EPISMO_TOKEN"

includeSnapshot=true adds the captured pack content to the response. It is omitted by default.

Update a suggestion

PATCH /v1/suggestions/:id
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "title": "Add review step",
  "content": "Please add a reviewer approval step before publish."
}

Only the author can update a suggestion's title or content.

Resolve a suggestion

PATCH /v1/suggestions/:id/resolve
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "status": "applied"
}

status is one of open, applied, declined, or archived. Only the pack's owner can resolve a suggestion. Resolving changes only the status; apply the actual change with a pack update first when accepting a suggestion.

The same handlers are also mounted under the /v1/packs/suggestions prefix (/v1/packs/suggestions, /v1/packs/suggestions/search, /v1/packs/suggestions/:id, and /v1/packs/suggestions/:id/resolve).