Issue, Answering Session & Work Chain API Endpoints

Complete reference for issue, issue session, answering session, session question, and work chain REST API endpoints -- discover, clarify, track, and resolve codebase issues via AI.

15 min read
apiissuesissue-sessions

Issues represent discovered bugs, improvements, or tasks in your codebase. Issue sessions are AI-powered scanning runs that automatically find issues. Answering sessions let an AI agent generate and review clarification questions before executing complex work. Work chains group issues into execution sequences. Together, these 30 endpoints enable a full discover-clarify-track-resolve workflow.

Issue Endpoints

GET /api/v1/issues/list

List issues with optional filtering.

Query parameters:

  • status (optional) -- Filter by issue status
  • sessionId (optional) -- Filter by issue session
curl -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/issues/list?status=open"

GET /api/v1/issues/get

Retrieve a single issue by ID.

  • id (required) -- The issue document ID

POST /api/v1/issues/create

Create a new issue manually.

curl -X POST -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Memory leak in WebSocket handler",
    "description": "Connection handlers not cleaned up on disconnect",
    "priority": "high",
    "suggestedPrompt": "Fix the memory leak in src/ws/handler.ts by cleaning up event listeners on disconnect",
    "sessionId": "..."
  }' \
  https://<deployment>.convex.site/api/v1/issues/create

Body fields:

  • title (string, required) -- Issue title
  • description (string, optional) -- Detailed description
  • priority (string, optional) -- Priority level (e.g., high, medium, low)
  • suggestedPrompt (string, optional) -- AI prompt to fix the issue
  • sessionId (string, optional) -- Link to discovery session

POST /api/v1/issues/update

Update an existing issue.

{
  "issueId": "...",
  "title": "Updated title",
  "priority": "critical",
  "suggestedPrompt": "Updated fix instructions"
}

Fields: issueId (required), plus optional title, description, priority, suggestedPrompt.

POST /api/v1/issues/delete

Delete an issue.

{ "issueId": "..." }

POST /api/v1/issues/link-run

Link a workflow run to an issue (marks the issue as being worked on).

{ "issueId": "...", "runId": "..." }

POST /api/v1/issues/bulk-delete

Delete multiple issues.

{ "issueIds": ["id1", "id2", "id3"] }

Issue Session Endpoints

GET /api/v1/issue-sessions/list

List all issue scanning sessions for the project.

GET /api/v1/issue-sessions/get

Retrieve a single issue session.

  • id (required) -- The session document ID

POST /api/v1/issue-sessions/rename

Rename an issue session.

{ "sessionId": "...", "name": "Security Audit Scan" }

POST /api/v1/issue-sessions/delete

Soft-delete an issue session.

{ "sessionId": "..." }

POST /api/v1/issue-sessions/restore

Restore a soft-deleted issue session.

{ "sessionId": "..." }

POST /api/v1/issue-sessions/permanent-delete

Permanently delete an issue session.

{ "sessionId": "..." }

POST /api/v1/issue-sessions/bulk-delete

Soft-delete multiple issue sessions.

{ "sessionIds": ["id1", "id2"] }

POST /api/v1/issue-sessions/start

Start a new AI-powered issue scanning session. Provisions a sandbox that analyzes your codebase and discovers issues.

curl -X POST -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Scan for security vulnerabilities and performance issues",
    "templateId": "base",
    "memoryMb": 4096,
    "timeoutMs": 600000
  }' \
  https://<deployment>.convex.site/api/v1/issue-sessions/start

Required: prompt. Optional: templateId, memoryMb, cpuCount, timeoutMs.

Response (201 Created):

{ "data": { "id": "...", "status": "active" } }

Answering Sessions

Answering sessions allow an AI agent to generate clarification questions before undertaking complex work. A human (or automated system) reviews each question, either approving the agent's assumption or providing a correction. The agent then proceeds with the reviewed answers as additional context.

Answering sessions are linked to an issue session via issueSessionId. The full workflow is:

  1. Start an issue session (POST /api/v1/issue-sessions/start)
  2. Create an answering session for it (POST /api/v1/answering-sessions)
  3. The agent populates questions via the Trigger.dev callback
  4. Review each question via PUT /api/v1/session-questions/:id/review
  5. Update the session status to reviewed to signal the agent to proceed

Answering Session Object

{
  "id": "as_...",
  "issueSessionId": "is_...",
  "projectId": "proj_...",
  "status": "pending",
  "questionCount": 5,
  "reviewedCount": 3,
  "createdAt": "2024-01-15T10:00:00Z",
  "completedAt": null
}

Session status values: pending (created, waiting for questions), active (questions generated, awaiting review), reviewed (all questions reviewed, agent may proceed), completed (agent finished with answers), archived (soft-deleted).

GET /api/v1/answering-sessions

List answering sessions for the project.

Query parameters:

  • issueSessionId (optional) -- Filter by parent issue session
  • status (optional) -- Filter by session status
curl -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/answering-sessions?status=active"

GET /api/v1/answering-sessions/:id

Get a single answering session by ID.

curl -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/answering-sessions/as_..."

Response:

{
  "data": {
    "id": "as_...",
    "issueSessionId": "is_...",
    "status": "active",
    "questionCount": 5,
    "reviewedCount": 0,
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

POST /api/v1/answering-sessions

Create a new answering session linked to an issue session.

curl -X POST -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "issueSessionId": "is_..."
  }' \
  https://<deployment>.convex.site/api/v1/answering-sessions

Body fields:

  • issueSessionId (string, required) -- The parent issue session this answering session belongs to

Response (201 Created):

{ "data": { "id": "as_...", "status": "pending" } }

PUT /api/v1/answering-sessions/:id/status

Update the status of an answering session.

curl -X PUT -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "reviewed" }' \
  https://<deployment>.convex.site/api/v1/answering-sessions/as_.../status

Body fields:

  • status (string, required) -- New status: pending, active, reviewed, completed, or archived

DELETE /api/v1/answering-sessions/:id

Archive (soft-delete) an answering session. The session is moved to trash and can be restored. Use the permanent-delete trash endpoint to fully remove it.

curl -X DELETE -H "Authorization: Bearer cc_live_..." \
  https://<deployment>.convex.site/api/v1/answering-sessions/as_...

Session Questions

Session questions are the individual clarification items within an answering session. The AI agent generates an initial assumption for each question; reviewers can approve the assumption or provide a correction.

Session Question Object

{
  "id": "sq_...",
  "answeringSessionId": "as_...",
  "question": "Should the dark mode preference persist across browser sessions?",
  "assumption": "Yes -- use localStorage to persist the preference indefinitely.",
  "correction": null,
  "status": "pending",
  "reviewedAt": null,
  "reviewedBy": null
}

Question status values: pending (awaiting review), approved (reviewer accepted the assumption), declined (reviewer provided a correction).

GET /api/v1/session-questions

List questions for a given answering session.

Query parameters:

  • answeringSessionId (required) -- The answering session to list questions for
curl -H "Authorization: Bearer cc_live_..." \
  "https://<deployment>.convex.site/api/v1/session-questions?answeringSessionId=as_..."

Response:

{
  "data": [
    {
      "id": "sq_...",
      "question": "Should the dark mode preference persist?",
      "assumption": "Yes -- use localStorage.",
      "correction": null,
      "status": "pending"
    }
  ]
}

PUT /api/v1/session-questions/:id/review

Review a question by approving the agent's assumption or declining it with a correction. When you decline, provide the correct answer in correction.

# Approve the assumption
curl -X PUT -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "approved" }' \
  https://<deployment>.convex.site/api/v1/session-questions/sq_.../review

# Decline and provide a correction
curl -X PUT -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "status": "declined",
    "correction": "No -- use a server-side cookie tied to the user account instead."
  }' \
  https://<deployment>.convex.site/api/v1/session-questions/sq_.../review

Body fields:

  • status (string, required) -- Review decision: approved or declined
  • correction (string, required when status is declined) -- The correct answer or instruction that overrides the agent's assumption

Warning

If you decline a question without providing a correction, the endpoint returns a 400 error. The correction is the authoritative answer the agent will use -- an empty correction would leave the agent with no guidance.

PUT /api/v1/session-questions/:id/assumption

Update the AI-generated assumption for a question without changing its review status. Use this to pre-populate or correct the assumption text before the formal review step.

curl -X PUT -H "Authorization: Bearer cc_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "assumption": "Use localStorage with a 30-day expiry for guest users and sync to the user account on sign-in."
  }' \
  https://<deployment>.convex.site/api/v1/session-questions/sq_.../assumption

Body fields:

  • assumption (string, required) -- The updated assumption text

Work Chain Endpoints

GET /api/v1/work-chains/list

List all work chains for the project.

GET /api/v1/work-chains/get

Retrieve a work chain by ID.

  • id (required) -- The work chain document ID

GET /api/v1/work-chains/issues

Get all issues linked to a work chain.

  • id (required) -- The work chain document ID

POST /api/v1/work-chains/create

Create a new work chain from a set of issues.

{
  "title": "Security Fix Chain",
  "description": "Fix all security issues found in audit",
  "issueIds": ["issue1", "issue2"],
  "workflowId": "...",
  "githubRepoUrl": "https://github.com/org/repo",
  "branchName": "fix/security-issues"
}

POST /api/v1/work-chains/delete

Delete a work chain.

{ "chainId": "..." }

POST /api/v1/work-chains/start

Start executing a work chain.

{ "chainId": "..." }

Response (201 Created):

{ "data": { "id": "...", "status": "running" } }