# GetResolved API v1

> Customer support platform API. Manage issues (to-dos extracted from customer conversations), conversations, and releases.

## Auth
All requests require `Authorization: Bearer gr_...` header. API keys are scoped to a workspace — all data returned is filtered to that workspace.

## Quick Start
- List pending issues: GET /api/v1/issues?status=pending
- Create an issue: POST /api/v1/issues {"product_id":"...","title":"..."}
- Start working on an issue: PATCH /api/v1/issues/{id} {"status":"in_progress"}
- Mark issue done: PATCH /api/v1/issues/{id} {"status":"done"}
- Leave a fix note: PATCH /api/v1/issues/{id} {"resolution_comment":"fixed in v2.4"}
- See linked conversations: GET /api/v1/issues/{id}
- Read a conversation: GET /api/v1/conversations/{id}
- Create a release: POST /api/v1/releases {"product_id":"...","title":"...","issue_ids":["..."]}
- Add a message to a conversation: POST /api/v1/conversations/{id}/messages {"body":"..."}

## Endpoints

### Identity
- GET /api/v1/me — Returns { workspace_id, api_key_id, member }. `member` is the workspace member tied to this API key (or null). Use to discover your own member id for use as `assignee_id`.
- GET /api/v1/members — List workspace members. Each entry has { id, user_id, role, display_name, avatar_url, created_at }. Params: limit, offset.

### Products
- GET /api/v1/products — List products. Params: limit, offset
- POST /api/v1/products — Create product. Body: { name, slug? }. Slug is derived from name if omitted; auto-suffixed on collision. Returns 201 with the created product (includes widget_key).
- GET /api/v1/products/{id} — Get product
- PATCH /api/v1/products/{id} — Update product. Body: { name?, slug?, issue_prefix?, widget_config?, domain? }. Slug and issue_prefix must remain unique within the workspace. Changing issue_prefix only affects newly created issues (existing shortcodes are immutable).

### Issues (to-dos extracted from customer conversations)
- GET /api/v1/issues — List issues. Each issue includes a `shortcode` (e.g. GET-005) plus its UUID. Params: product_id, status (comma-sep: pending,in_progress,icebox,done,released,dismissed), priority (comma-sep: low,normal,high,urgent), assignee_id (comma-sep member ids, or "none" for unassigned), limit, offset
- POST /api/v1/issues — Create issue. Body: { product_id, title, description?, status? (default pending), priority? (default normal), assignee_id? }. Shortcode is auto-generated. Returns 201.
- POST /api/v1/issues/maybe — Deduplicating create. Same body as POST /issues, but first asks an AI to compare against pending/in_progress/icebox issues for the product (matches across paraphrasing and translation). On match: returns 200 with { data: <existing_issue>, matched_existing: true, api_source_id }. On no match: creates and returns 201 with { data: <new_issue>, matched_existing: false, api_source_id }. Either way the request is logged in `issue_api_sources` for provenance.
- GET /api/v1/issues/{id} — Get issue with linked conversations. `{id}` can be the UUID or the shortcode (e.g. /api/v1/issues/GET-005)
- PATCH /api/v1/issues/{id} — Update issue. `{id}` accepts UUID or shortcode. Body: { status?, priority?, assignee_id? (member id, the string "me" to assign to the API key's owning member, or null to unassign), resolution_comment? (string or null to clear) }

Note: /api/v1/actions is a deprecated alias for /api/v1/issues and works identically.

### Conversations (tickets, ideas, feedback, chats)
- GET /api/v1/conversations — List conversations. Params: product_id, type (comma-sep: ticket,idea,feedback,chat), status (comma-sep: open,in_progress,resolved), priority, limit, offset. Each conversation has a `source` field: `chat` for widget conversations, `form` for form submissions mirrored into the inbox.
- GET /api/v1/conversations/{id} — Get conversation with messages
- PATCH /api/v1/conversations/{id} — Update conversation. Body: { status?, priority? }
- POST /api/v1/conversations/{id}/messages — Add message. Body: { body }

Note: /api/v1/items is a deprecated alias for /api/v1/conversations and works identically.

### Releases
- GET /api/v1/releases — List releases. Params: product_id, limit, offset
- POST /api/v1/releases — Create release. Body: { product_id, title, description?, version?, issue_ids? }
- GET /api/v1/releases/{id} — Get release with linked issues

### Discovery
- GET /api/v1/openapi.json — Full OpenAPI 3.1 spec
- GET /api/v1/llms.txt — This file

## Status Flows
- Issues: pending -> in_progress -> done -> released | dismissed (released is set automatically when the issue is linked to a release via POST /releases). Any non-terminal state can be parked into `icebox` (valid but deferred pending a product decision) and brought back later.
- Conversations: open -> in_progress -> resolved

## Response Format
Lists return: { data: [...], pagination: { total, limit, offset } }
Singles return: { data: { ... } }
Errors return: { error_code: "...", detail: "..." }

## Pagination
All list endpoints accept limit (default 50, max 200) and offset (default 0).