Wins

Wins are the core resource in Hype Doc — each win represents an achievement or accomplishment.

List wins

GET /api/v1/wins

Returns a paginated list of wins, newest first.

Query parameters

Parameter	Type	Description
space_id	integer	Filter by space ID
tag	string	Filter by tag name
since	date	Only wins on or after this date (YYYY-MM-DD)
until	date	Only wins on or before this date (YYYY-MM-DD)
q	string	Full-text search on win content
page	integer	Page number (default: 1)
per_page	integer	Items per page (default: 25, max: 100)

Example

Request

curl "https://app.myhypedoc.com/api/v1/wins?space_id=1&tag=launch&since=2026-01-01" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

[
  {
    "id": 42,
    "body_html": "<p>Shipped the new onboarding flow</p>",
    "body_text": "Shipped the new onboarding flow",
    "occurred_on": "2026-01-15",
    "space": {
      "id": 1,
      "name": "Work",
      "emoji": "💼"
    },
    "tags": [
      { "id": 5, "name": "launch" }
    ],
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-01-15T10:30:00Z"
  }
]

Get a win

GET /api/v1/wins/:id

Returns a single win by ID.

Create a win

POST /api/v1/wins

Request body

Field	Type	Required	Description
win[body]	string	Yes	The win content (plain text, HTML, or markdown)
win[body_format]	string	No	"markdown" to auto-render markdown to HTML. Omit for raw HTML.
win[space_id]	integer	Yes	The space to log the win in
win[occurred_on]	date	No	Date in YYYY-MM-DD format (defaults to today)
win[tag_names]	array or string	No	Tags to apply. Array of strings, or comma-separated string.

Example

Request

curl -X POST https://app.myhypedoc.com/api/v1/wins \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "win": {
      "body": "**Shipped** the new onboarding flow with 3 steps",
      "body_format": "markdown",
      "space_id": 1,
      "occurred_on": "2026-01-15",
      "tag_names": ["launch", "product"]
    }
  }'

Response (201)

{
  "id": 42,
  "body_html": "<p><strong>Shipped</strong> the new onboarding flow with 3 steps</p>",
  "body_text": "Shipped the new onboarding flow with 3 steps",
  "occurred_on": "2026-01-15",
  "space": {
    "id": 1,
    "name": "Work",
    "emoji": "💼"
  },
  "tags": [
    { "id": 5, "name": "launch" },
    { "id": 6, "name": "product" }
  ],
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-01-15T10:30:00Z"
}

Markdown support

When body_format is set to "markdown", the body is rendered to HTML using Redcarpet with support for:

• Autolinks
• Tables
• Fenced code blocks
• Strikethrough
• Hard line breaks

Update a win

PATCH /api/v1/wins/:id

Accepts the same fields as create. Only send the fields you want to change. To update tags, include win[tag_names] — this replaces all existing tags.

Delete a win

DELETE /api/v1/wins/:id

Returns 204 No Content on success.

Errors

Status	Meaning
401	Missing or invalid token
402	Free plan limit reached
404	Win not found
422	Validation error (e.g. missing body)