TaskForge
Back to documentation

Task API

Ticket Draft Generation

Submit a product or technical spec, poll an asynchronous model job, and retrieve canonical provider-neutral ticket drafts. IssueHub or another upstream system owns provider sync after generation.

OpenAPI JSON Proto Result schema

What a Client Needs

  1. An API key created in the admin UI at /admin/clients.
  2. Scopes: tickets:submit, tickets:read, and optionally tickets:cancel.
  3. A bearer token header on REST and gRPC calls: Authorization: Bearer <api_key>.
  4. A stable idempotency_key for retry-safe submissions.

REST Flow

1. Submit a job

curl -sS -X POST http://127.0.0.1:8080/tickets/v1/jobs \
  -H "Authorization: Bearer $TASKFORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schema_version": "tickets.input.v1",
    "idempotency_key": "spec-job-uuid-or-stable-client-key",
    "title": "Customer Billing Reconciliation Workspace",
    "spec": "Full or condensed product/technical spec text",
    "options": {
      "ticket_count": 3,
      "max_ticket_count": 6,
      "include_epics": true,
      "dependency_mode": "explicit",
      "output_detail": "standard"
    }
  }'

2. Poll status

curl -sS http://127.0.0.1:8080/tickets/v1/jobs/$JOB_ID \
  -H "Authorization: Bearer $TASKFORGE_API_KEY"

3. Fetch result

curl -sS http://127.0.0.1:8080/tickets/v1/jobs/$JOB_ID/result \
  -H "Authorization: Bearer $TASKFORGE_API_KEY"

Submit Response

{
  "schema_version": "tickets.job.v1",
  "job_id": "019e4fae-f96a-78b2-be03-8633c38ea640",
  "status": "queued",
  "status_url": "/tickets/v1/jobs/019e4fae-f96a-78b2-be03-8633c38ea640",
  "result_url": "/tickets/v1/jobs/019e4fae-f96a-78b2-be03-8633c38ea640/result",
  "created_at": "2026-05-22T12:35:27.722228+00:00"
}

Canonical Result

Results return one top-level tickets[] array. TaskForge does not return github_issues[] or jira_tickets[] as primary result lists. 

{
  "schema_version": "tickets.result.v1",
  "job_id": "019e4fae-f96a-78b2-be03-8633c38ea640",
  "source": {
    "title": "Customer Billing Reconciliation Workspace",
    "summary": "Workspace for finance and support teams to investigate customer billing discrepancies."
  },
  "tickets": [
    {
      "external_id": "SPEC-1",
      "ticket_type": "story",
      "title": "Show invoices, payments, refunds, and credits",
      "description": "Display billing records needed to investigate customer discrepancies.",
      "acceptance_criteria": ["Invoice table shows number, status, amount, and due date."],
      "labels": ["billing", "ui"],
      "dependencies": [],
      "story_points": 5,
      "priority": "high",
      "parent_external_id": null,
      "metadata": {
        "component": "billing",
        "suggested_milestone": "Billing reconciliation",
        "confidence": 0.84
      }
    }
  ],
  "risks": [],
  "open_questions": [],
  "generation": {
    "model": "qwen3:1.7b",
    "duration_ms": 388400,
    "prompt_tokens": null,
    "completion_tokens": null,
    "finish_reason": "stop"
  }
}

Endpoints and Scopes

MethodPathScopePurpose
POST/tickets/v1/jobstickets:submitCreate an async ticket-generation job.
POST/v1/task-generation/jobstickets:submitCompatibility alias for submit.
GET/tickets/v1/jobstickets:readList jobs owned by the API key's client.
GET/tickets/v1/jobs/{job_id}tickets:readRead job status.
GET/tickets/v1/jobs/{job_id}/resulttickets:readRead completed result JSON.
DELETE/tickets/v1/jobs/{job_id}tickets:cancelRequest job cancellation.
GET/tickets/v1/schematickets:readRead schema metadata and result schema.

Ticket Rules

gRPC

Use package taskforge.tickets.v1, service TicketsService. The public proto is published at /openapi/tickets.v1.proto. 

grpcurl -plaintext \
  -H "authorization: Bearer $TASKFORGE_API_KEY" \
  -d '{"schema_version":"tickets.input.v1","idempotency_key":"stable-key","title":"Plan","spec":"Build it"}' \
  127.0.0.1:50051 taskforge.tickets.v1.TicketsService/SubmitJob