Programmatic Issue Creation

Short answer

Teams can create internal TestChimp issues programmatically using POST /api/mcp/upsert_issue (omit issueId), authenticated with a project API key. The same contract is available through the TestChimp CLI and MCP tool (upsert-issue). Use simple flags for quick creates, or pass a full JSON body for detailed issue intake from CI pipelines and custom scanners. POST /api/mcp/create_issue remains a hidden alias.

When to use this

Use programmatic creation when issues should be filed automatically from systems outside the TestChimp UI—for example:

• Custom security or quality scanners run in CI
• Monitoring or observability pipelines that open triage items
• Release automation that records findings as issues
• Agent workflows that call TestChimp over HTTP

Created issues land in the same Issues backlog as UI-created and agent-created items.

Authentication and project scope

Item	Value
Endpoint	POST /api/mcp/upsert_issue (omit issueId to create; hidden alias POST /api/mcp/create_issue)
Auth header	TestChimp-Api-Key: <project-api-key>
Project	Resolved from the API key (do not pass project id in the body)
Backend base URL	Your TestChimp deployment URL (e.g. https://app.testchimp.io)

Optional environment variable for CLI/MCP:

• TESTCHIMP_BACKEND_URL — overrides the default backend URL
• TESTCHIMP_API_KEY — required for CLI/MCP calls

Request contract

title is the only required field. All other fields are optional.

Simple fields

Field	Type	Notes
title	string	Required. Issue title
description	string	Markdown-supported description
issueType	enum	BUG_ISSUE (default), SUGGESTION_ISSUE, OBSERVATION_ISSUE, TASK_ISSUE
category	enum	e.g. FUNCTIONAL, SECURITY, ACCESSIBILITY, PERFORMANCE
severity	enum	LOW_SEVERITY, MEDIUM_SEVERITY (default), HIGH_SEVERITY, CRITICAL_SEVERITY
status	enum	Defaults to ACTIVE
reportedReleaseId	string	Release label/id
dueDateMillis	int64	UTC due date in epoch millis
assignee	string	Assignee user id
environment	string	Defaults to QA when omitted
source	string	Stored as label source:<value> for ingest provenance
labels	string[]	Additional labels
linkTargets	object[]	{ "toEntityType": "SCENARIO", "toEntityId": "42" }
attachments	object[]	Attachment objects (filename, url, …)
artifactReference	object	Artifact locator for the issue viewer

linkTargets.toEntityType values

STORY, SCENARIO, TEST, ISSUE, EXTERNAL, TEST_EXECUTION, BATCH_INVOCATION

Response contract

{
  "status": "ok",
  "ordinalId": 123,
  "issueId": "B-123",
  "issue": {
    "ordinalId": 123,
    "title": "Login button unresponsive",
    "description": "…",
    "status": "ACTIVE",
    "severity": "MEDIUM_SEVERITY",
    "issueType": "BUG_ISSUE"
  }
}

• ordinalId / issueId — use for follow-up calls such as POST /api/mcp/get_issue_details or POST /api/mcp/upsert_issue (set issueId to patch)
• issue — echo of the created issue; includes linkedEntities when linkTargets or attachments were provided

HTTP example

curl -sS -X POST "$TESTCHIMP_BACKEND_URL/api/mcp/upsert_issue" \
  -H "Content-Type: application/json" \
  -H "TestChimp-Api-Key: $TESTCHIMP_API_KEY" \
  -d '{
    "title": "Custom scanner: exposed admin endpoint",
    "description": "Found by nightly route scan.\n\nPath: /admin/debug",
    "severity": "HIGH_SEVERITY",
    "category": "SECURITY",
    "source": "nightly-route-scan",
    "labels": ["ci", "security"]
  }'

CLI examples

Simple create (flags)

export TESTCHIMP_API_KEY=...
export TESTCHIMP_BACKEND_URL=https://app.testchimp.io

testchimp upsert-issue \
  --title "CI smoke: checkout failed" \
  --description "Playwright smoke test failed on main." \
  --severity HIGH_SEVERITY \
  --category FUNCTIONAL \
  --labels ci,smoke \
  --source ci-smoke

Full create (JSON file)

issue.json:

{
  "title": "Dependency audit: critical CVE",
  "description": "Trivy reported CVE-2024-0001 in lodash.",
  "issueType": "BUG_ISSUE",
  "category": "SECURITY",
  "severity": "CRITICAL_SEVERITY",
  "reportedReleaseId": "2026.03.1",
  "source": "deps-scan",
  "labels": ["ci", "deps"],
  "linkTargets": [
    { "toEntityType": "SCENARIO", "toEntityId": "15" }
  ]
}

testchimp upsert-issue --json-input @issue.json

--json-input merges over flags; when both are present, JSON wins on key conflicts.

MCP tool

The MCP server registers an upsert-issue tool with the same input schema as the CLI (omit issueId to create). Configure TESTCHIMP_API_KEY (and optionally TESTCHIMP_BACKEND_URL) in your MCP client. See MCP API v2 migration.

Defaults and validation

• Missing status → ACTIVE
• Missing issueType → BUG_ISSUE
• Missing severity → MEDIUM_SEVERITY
• Missing environment → QA
• Empty or missing title → 400 with title is required
• Invalid linkTargets entries are skipped; valid targets are linked after create
• source is stored as a source:<value> label (deduped if you also pass the same label in labels)
• API-created issues are not attributed to ExploreChimp; use source / labels for provenance

CLI flags (simple path)

Flag	Maps to
--title	title
--description	description
--issue-type	issueType
--category	category
--severity	severity
--status	status
--reported-release-id	reportedReleaseId
--due-date-millis	dueDateMillis
--assignee	assignee
--labels	labels (comma-separated)
--source	source
--environment	environment
--json-input	full body; merges over flags (JSON wins)

Related documentation

• How Issues Get Created — UI and agent intake paths
• Issue page — fields you can refine after create
• List view and kanban — triage created issues

Frequently asked questions

Can I create issues from CI without using the UI?

Yes. Call POST /api/mcp/upsert_issue (omit issueId) with your project API key, or use testchimp upsert-issue in a pipeline step. Issues appear in the same Issues backlog as manually created items.

What is the minimum payload?

A JSON body with title only. All other fields are optional.

How do I pass a full detailed bug in one call?

Use --json-input with a JSON file or inline object containing description, severity, category, labels, linkTargets, attachments, and other supported fields.

Does this create GitHub issues?

No. This endpoint creates internal TestChimp issues only. GitHub issue export is a separate integration flow.

Wire external signals into your issue backlog

Point CI scanners and custom automation at upsert_issue so findings become tracked TestChimp issues with provenance labels.

Start free on TestChimp · Book a demo

Related pages