Issues

The Issues API lets server-side integrations create and manage support issues in the same workspace-scoped issue model used by the Woes operator app and client portal.

The REST Issues API does not expose internal notes, raw metadata, workspace ids, operator-only debug fields, or provider details.

Issue Object

{
  "object": "issue",
  "id": "7f6d1d2c-7e21-4f5e-9f60-23d8f67121a2",
  "subject": "OAuth redirect URI mismatch",
  "preview": "Customer reports a redirect_uri mismatch on the production OAuth app.",
  "description": "Customer reports a redirect_uri mismatch on the production OAuth app.",
  "statusCategory": "new",
  "priority": "high",
  "tags": ["oauth", "production"],
  "customer": {
    "name": "Ada Lovelace",
    "email": "ada@example.com",
    "company": "Example API Co"
  },
  "source": {
    "channel": "api",
    "conversationId": null
  },
  "externalLinks": [
    {
      "provider": "linear",
      "key": "ENG-123",
      "url": "https://linear.app/example/issue/ENG-123/oauth-redirect-uri-mismatch",
      "status": "In Progress"
    }
  ],
  "createdAt": "2026-06-29T13:00:00.000Z",
  "updatedAt": "2026-06-29T13:00:00.000Z",
  "lastActivityAt": "2026-06-29T13:00:00.000Z",
  "closedAt": null
}

List Issues

GET /api/v1/issues

Query parameters:

Parameter	Type	Description
`limit`	number	1-100 issues. Default: `20`.
`statusCategory`	string	`new`, `on_you`, `on_customer`, `on_hold`, or `closed`.
`priority`	string	Priority label, such as `medium`, `high`, or a custom workspace priority string.
`customerEmail`	string	Customer email stored on the issue.
`sourceConversationId`	string	Conversation id linked to the issue.

curl "https://woes.dev/api/v1/issues?statusCategory=new&limit=10" \
  -H "Authorization: Bearer $WOES_API_KEY"

{
  "object": "list",
  "hasMore": false,
  "issues": [
    {
      "object": "issue",
      "id": "7f6d1d2c-7e21-4f5e-9f60-23d8f67121a2",
      "subject": "OAuth redirect URI mismatch",
      "preview": "Customer reports a redirect_uri mismatch on the production OAuth app.",
      "description": "Customer reports a redirect_uri mismatch on the production OAuth app.",
      "statusCategory": "new",
      "priority": "high",
      "tags": ["oauth", "production"],
      "customer": {
        "name": "Ada Lovelace",
        "email": "ada@example.com",
        "company": "Example API Co"
      },
      "source": {
        "channel": "api",
        "conversationId": null
      },
      "externalLinks": [
        {
          "provider": "linear",
          "key": "ENG-123",
          "url": "https://linear.app/example/issue/ENG-123/oauth-redirect-uri-mismatch",
          "status": "In Progress"
        }
      ],
      "createdAt": "2026-06-29T13:00:00.000Z",
      "updatedAt": "2026-06-29T13:00:00.000Z",
      "lastActivityAt": "2026-06-29T13:00:00.000Z",
      "closedAt": null
    }
  ]
}

Create Issue

POST /api/v1/issues

Request body:

Field	Type	Required	Description
`subject`	string	Yes	Issue title, up to 180 characters.
`description`	string	No	Issue details, up to 8,000 characters.
`priority`	string	No	Defaults to `medium`; 1-32 characters.
`statusCategory`	string	No	Defaults to `new`.
`tags`	array	No	Up to 25 tag labels; duplicates are removed case-insensitively.
`customer.name`	string	No	Customer display name.
`customer.email`	string	No	Customer email address.
`customer.company`	string	No	Customer company or account name.
`sourceConversationId`	string	No	Existing conversation id to link; must belong to the same workspace.
`sourceChannel`	string	No	Defaults to `api` when no linked conversation is supplied.

curl https://woes.dev/api/v1/issues \
  -X POST \
  -H "Authorization: Bearer $WOES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "OAuth redirect URI mismatch",
    "description": "Customer reports a redirect_uri mismatch on the production OAuth app.",
    "priority": "high",
    "customer": {
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "company": "Example API Co"
    },
    "tags": ["oauth", "production"]
  }'

Response: 201 Created

{
  "issue": {
    "object": "issue",
    "id": "7f6d1d2c-7e21-4f5e-9f60-23d8f67121a2",
    "subject": "OAuth redirect URI mismatch",
    "preview": "Customer reports a redirect_uri mismatch on the production OAuth app.",
    "description": "Customer reports a redirect_uri mismatch on the production OAuth app.",
    "statusCategory": "new",
    "priority": "high",
    "tags": ["oauth", "production"],
    "customer": {
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "company": "Example API Co"
    },
    "source": {
      "channel": "api",
      "conversationId": null
    },
    "externalLinks": [],
    "createdAt": "2026-06-29T13:00:00.000Z",
    "updatedAt": "2026-06-29T13:00:00.000Z",
    "lastActivityAt": "2026-06-29T13:00:00.000Z",
    "closedAt": null
  }
}

Retrieve Issue

GET /api/v1/issues/{issueId}

curl https://woes.dev/api/v1/issues/7f6d1d2c-7e21-4f5e-9f60-23d8f67121a2 \
  -H "Authorization: Bearer $WOES_API_KEY"

External Links

Issue responses include externalLinks, an array of customer-safe links to external product or engineering work. Today those links are Linear-shaped:

Field	Description
`provider`	External provider, such as `linear`.
`key`	Human-readable external issue key.
`url`	Direct URL to the external issue when available.
`status`	External issue status when available.

The API does not return private integration credentials, webhook details, or operator-only notes.

Update Issue

PATCH /api/v1/issues/{issueId}

Supported fields:

Field	Type	Description
`subject`	string	Updated issue title.
`description`	string	Updated issue description.
`priority`	string	1-32 character priority label.
`statusCategory`	string	`new`, `on_you`, `on_customer`, `on_hold`, or `closed`.
`tags`	array	Replacement tag list.
`customer`	object	Replacement customer name, email, and/or company fields.

curl https://woes.dev/api/v1/issues/7f6d1d2c-7e21-4f5e-9f60-23d8f67121a2 \
  -X PATCH \
  -H "Authorization: Bearer $WOES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "statusCategory": "closed",
    "tags": ["oauth", "resolved"]
  }'

Tenant Boundary

Every Issues API call is scoped to the workspace attached to the API key. If an issue id or source conversation id belongs to another workspace, Woes returns 404 instead of revealing that the record exists.

Required Scopes

Endpoint	Scope
`GET /api/v1/issues`	`issues:read`
`POST /api/v1/issues`	`issues:write`
`GET /api/v1/issues/{issueId}`	`issues:read`
`PATCH /api/v1/issues/{issueId}`	`issues:write`

​Issues

​Issue Object

​List Issues

​Create Issue

​Retrieve Issue

​External Links

​Update Issue

​Tenant Boundary

​Required Scopes

Issues

Issue Object

List Issues

Create Issue

Retrieve Issue

External Links

Update Issue

Tenant Boundary

Required Scopes