Execution Tickets

Overview

The Execution API generates scoped engineering tickets from document blocks. Tickets can be reviewed, edited, and pushed to GitHub, Linear, or Jira. Status sync keeps Praxiom in sync with your issue tracker.

---

Generate Tickets

POST /api/execution/generate

Generate tickets from a document's blocks using the AI agent.

Request Body

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID
document_id	UUID	Yes	Document to generate tickets from
include_block_types	string[]	No	Filter to specific block types (e.g., ["user_story", "solution"])

Response (200 OK)

{
  "tickets": [
    {
      "id": "a1b2c3d4-...",
      "document_id": "e5f6a7b8-...",
      "block_id": "b2c3d4e5-...",
      "workspace_id": "550e8400-...",
      "title": "Implement step 3 progress indicator",
      "body": "## Context\nUsers are dropping off at step 3...\n\n## Acceptance Criteria\n- [ ] Progress bar visible...",
      "ticket_type": "task",
      "priority": "P1",
      "labels": ["onboarding", "ux"],
      "acceptance_criteria": ["Progress bar visible at all times", "Step count shown"],
      "estimated_effort": "medium",
      "status": "generated",
      "created_at": "2026-03-27T14:00:00Z"
    }
  ],
  "total": 5
}

---

List Tickets

GET /api/execution/{document_id}/tickets

List all generated tickets for a document.

Query Parameters

Name	Type	Required	Description
status	string	No	Filter by status: generated, reviewed, pushed, push_failed, synced

---

Edit Ticket

PATCH /api/execution/tickets/{ticket_id}

Edit a ticket before pushing. This is the review step.

Request Body

Name	Type	Required	Description
title	string	No	Updated title
body	string	No	Updated description
priority	string	No	P0, P1, P2, or P3
labels	string[]	No	Updated labels
acceptance_criteria	string[]	No	Updated criteria
estimated_effort	string	No	Updated effort estimate

---

Push Tickets

POST /api/execution/push

Bulk push tickets to an external platform.

Request Body

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID
document_id	UUID	Yes	Document ID
platform	string	Yes	Target platform: github, linear, or jira
ticket_ids	UUID[]	No	Specific tickets to push (default: all reviewed)

Response (200 OK)

{
  "results": [
    {
      "ticket_id": "a1b2c3d4-...",
      "status": "pushed",
      "external_url": "https://github.com/acme/app/issues/42",
      "external_id": "42"
    }
  ],
  "pushed": 4,
  "failed": 1
}

Platform Priority Mapping

Priority	GitHub	Linear	Jira
P0	Label: priority:critical	Urgent (1)	Highest
P1	Label: priority:high	High (2)	High
P2	Label: priority:medium	Medium (3)	Medium
P3	Label: priority:low	Low (4)	Low

---

Sync Tickets

POST /api/execution/sync

Sync ticket status from external platforms back to Praxiom.

Request Body

Name	Type	Required	Description
workspace_id	UUID	Yes	Workspace ID
document_id	UUID	Yes	Document ID

Response (200 OK)

{
  "results": [ ... ],
  "synced": 3,
  "unchanged": 1,
  "errors": 0
}