Create issue

The 201 response includes possibleDuplicates: open issues (in teams you can see) whose titles closely match, best first. Non-blocking — if one is the same work, comment on or update it instead of keeping the new issue. Pass dedupe=block to get 409 with the matches in details.possibleDuplicates instead of creating.

POST/workspaces/{organizationId}/issues

Authorization

AuthorizationBearer token · headerrequired

Workspace API key (Authorization: Bearer <key>). Issue keys under Settings → Developer or POST /workspaces/{organizationId}/tokens.

Path parameters

organizationIdstringrequired

Query parameters

dedupestring

warn (default): create and return possibleDuplicates; block: 409 when any possible duplicate exists

Allowed:warnblock

Request body

application/json

titlestringrequired

min length 1

externalRefstring | null

min length 1 · max length 255

teamIdstring

teamKeystring

descriptionstring | null

statusstring

Allowed:triagebacklogtodoin_progressdonecanceled

prioritystring

Allowed:lowmediumhighurgent

resolutionstring | null

Allowed:duplicatenot_plannedintended_behaviornot_reproducibleobsoleteresolvedskippednull

resolutionReasonstring | null

parentIdstring | null

subIssueSortOrdernumber | null

estimateinteger | null

min 0

isDraftboolean

sensitiveboolean

templateIdstring

snoozedUntilstring | null

assigneeIdstring | null

delegateIdstring | null

stepKeystring | null

requiredboolean

ownerAgentstring | null

projectIdstring | null

cycleIdstring | null

labelIdsstring[] | null

repostring | null

branchstring | null

Responses

200

Existing issue with the same externalRef (idempotent create)

idstringrequired

organizationIdstringrequired

externalRefstring | nullrequired

teamIdstringrequired

titlestringrequired

descriptionstring | nullrequired

statusstringrequired

Allowed:triagebacklogtodoin_progressdonecanceled

prioritystringrequired

Allowed:lowmediumhighurgent

resolutionstring | nullrequired

Allowed:duplicatenot_plannedintended_behaviornot_reproducibleobsoleteresolvedskippednull

resolutionReasonstring | nullrequired

parentIdstring | nullrequired

subIssueSortOrdernumber | nullrequired

estimatenumber | nullrequired

isDraftbooleanrequired

sensitivebooleanrequired

snoozedUntilstring | nullrequired

assigneeIdstring | nullrequired

delegateIdstring | nullrequired

stepKeystring | nullrequired

requiredbooleanrequired

ownerAgentstring | nullrequired

claimedBystring | nullrequired

claimedLeaseExpiresAtstring | nullrequired

claimEpochnumberrequired

projectIdstring | nullrequired

cycleIdstring | nullrequired

labelIdsstring[]required

numbernumber | nullrequired

identifierstring | nullrequired

repostring | nullrequired

branchstring | nullrequired

prUrlstring | nullrequired

prStatestring | nullrequired

prCheckStatestring | nullrequired

createdAtstringrequired

updatedAtstringrequired

subStepProgressobject | null

Show properties

totalintegerrequired

doneintegerrequired

blockedintegerrequired

ownerAgentstring | nullrequired

201

Issue created, with possible duplicates to review

idstringrequired

organizationIdstringrequired

externalRefstring | nullrequired

teamIdstringrequired

titlestringrequired

descriptionstring | nullrequired

statusstringrequired

Allowed:triagebacklogtodoin_progressdonecanceled

prioritystringrequired

Allowed:lowmediumhighurgent

resolutionstring | nullrequired

Allowed:duplicatenot_plannedintended_behaviornot_reproducibleobsoleteresolvedskippednull

resolutionReasonstring | nullrequired

parentIdstring | nullrequired

subIssueSortOrdernumber | nullrequired

estimatenumber | nullrequired

isDraftbooleanrequired

sensitivebooleanrequired

snoozedUntilstring | nullrequired

assigneeIdstring | nullrequired

delegateIdstring | nullrequired

stepKeystring | nullrequired

requiredbooleanrequired

ownerAgentstring | nullrequired

claimedBystring | nullrequired

claimedLeaseExpiresAtstring | nullrequired

claimEpochnumberrequired

projectIdstring | nullrequired

cycleIdstring | nullrequired

labelIdsstring[]required

numbernumber | nullrequired

identifierstring | nullrequired

repostring | nullrequired

branchstring | nullrequired

prUrlstring | nullrequired

prStatestring | nullrequired

prCheckStatestring | nullrequired

createdAtstringrequired

updatedAtstringrequired

subStepProgressobject | null

Show properties

totalintegerrequired

doneintegerrequired

blockedintegerrequired

ownerAgentstring | nullrequired

possibleDuplicatesPossibleDuplicate[]required

Show properties

Array of PossibleDuplicate

idstringrequired

identifierstring | nullrequired

titlestringrequired

statusstringrequired

Allowed:triagebacklogtodoin_progressdonecanceled

scorenumberrequired

Share of significant title terms in common with the new title (0-1)

409

dedupe=block and possible duplicates exist (details.possibleDuplicates)

codestringrequired

Allowed:CONFLICT

messagestringrequired

hintstringrequired

detailsobjectrequired

Show properties

possibleDuplicatesPossibleDuplicate[]required

Show properties

Array of PossibleDuplicate

idstringrequired

identifierstring | nullrequired

titlestringrequired

statusstringrequired

Allowed:triagebacklogtodoin_progressdonecanceled

scorenumberrequired

Share of significant title terms in common with the new title (0-1)

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer tokenRemember on this deviceInclude my values in samples

Parameters

organizationIdpath*dedupequerywarn (default): create and return possibleDuplicates; block: 409 when any possible duplicate exists

Bodyapplication/json

Request body

Request

curl -X POST 'https://pile.nyc/workspaces/string/issues' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "title": "string",
  "externalRef": "string",
  "teamId": "string",
  "teamKey": "string",
  "description": "string",
  "status": "triage",
  "priority": "low",
  "resolution": "duplicate",
  "resolutionReason": "string",
  "parentId": "string",
  "subIssueSortOrder": 0,
  "estimate": 0,
  "isDraft": true,
  "sensitive": true,
  "templateId": "string",
  "snoozedUntil": "string",
  "assigneeId": "string",
  "delegateId": "string",
  "stepKey": "string",
  "required": true,
  "ownerAgent": "string",
  "projectId": "string",
  "cycleId": "string",
  "labelIds": [
    "string"
  ],
  "repo": "string",
  "branch": "string"
}'

const response = await fetch("https://pile.nyc/workspaces/string/issues", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"title\": \"string\",\n  \"externalRef\": \"string\",\n  \"teamId\": \"string\",\n  \"teamKey\": \"string\",\n  \"description\": \"string\",\n  \"status\": \"triage\",\n  \"priority\": \"low\",\n  \"resolution\": \"duplicate\",\n  \"resolutionReason\": \"string\",\n  \"parentId\": \"string\",\n  \"subIssueSortOrder\": 0,\n  \"estimate\": 0,\n  \"isDraft\": true,\n  \"sensitive\": true,\n  \"templateId\": \"string\",\n  \"snoozedUntil\": \"string\",\n  \"assigneeId\": \"string\",\n  \"delegateId\": \"string\",\n  \"stepKey\": \"string\",\n  \"required\": true,\n  \"ownerAgent\": \"string\",\n  \"projectId\": \"string\",\n  \"cycleId\": \"string\",\n  \"labelIds\": [\n    \"string\"\n  ],\n  \"repo\": \"string\",\n  \"branch\": \"string\"\n}"
});

import requests

response = requests.post(
    "https://pile.nyc/workspaces/string/issues",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"title\": \"string\",\n  \"externalRef\": \"string\",\n  \"teamId\": \"string\",\n  \"teamKey\": \"string\",\n  \"description\": \"string\",\n  \"status\": \"triage\",\n  \"priority\": \"low\",\n  \"resolution\": \"duplicate\",\n  \"resolutionReason\": \"string\",\n  \"parentId\": \"string\",\n  \"subIssueSortOrder\": 0,\n  \"estimate\": 0,\n  \"isDraft\": true,\n  \"sensitive\": true,\n  \"templateId\": \"string\",\n  \"snoozedUntil\": \"string\",\n  \"assigneeId\": \"string\",\n  \"delegateId\": \"string\",\n  \"stepKey\": \"string\",\n  \"required\": true,\n  \"ownerAgent\": \"string\",\n  \"projectId\": \"string\",\n  \"cycleId\": \"string\",\n  \"labelIds\": [\n    \"string\"\n  ],\n  \"repo\": \"string\",\n  \"branch\": \"string\"\n}",
)

Response

{
  "id": "string",
  "organizationId": "string",
  "externalRef": "string",
  "teamId": "string",
  "title": "string",
  "description": "string",
  "status": "triage",
  "priority": "low",
  "resolution": "duplicate",
  "resolutionReason": "string",
  "parentId": "string",
  "subIssueSortOrder": 0,
  "estimate": 0,
  "isDraft": true,
  "sensitive": true,
  "snoozedUntil": "string",
  "assigneeId": "string",
  "delegateId": "string",
  "stepKey": "string",
  "required": true,
  "ownerAgent": "string",
  "claimedBy": "string",
  "claimedLeaseExpiresAt": "string",
  "claimEpoch": 0,
  "projectId": "string",
  "cycleId": "string",
  "labelIds": [
    "string"
  ],
  "number": 0,
  "identifier": "string",
  "repo": "string",
  "branch": "string",
  "prUrl": "string",
  "prState": "string",
  "prCheckState": "string",
  "createdAt": "string",
  "updatedAt": "string",
  "subStepProgress": {
    "total": 0,
    "done": 0,
    "blocked": 0,
    "ownerAgent": "string"
  }
}

{
  "id": "string",
  "organizationId": "string",
  "externalRef": "string",
  "teamId": "string",
  "title": "string",
  "description": "string",
  "status": "triage",
  "priority": "low",
  "resolution": "duplicate",
  "resolutionReason": "string",
  "parentId": "string",
  "subIssueSortOrder": 0,
  "estimate": 0,
  "isDraft": true,
  "sensitive": true,
  "snoozedUntil": "string",
  "assigneeId": "string",
  "delegateId": "string",
  "stepKey": "string",
  "required": true,
  "ownerAgent": "string",
  "claimedBy": "string",
  "claimedLeaseExpiresAt": "string",
  "claimEpoch": 0,
  "projectId": "string",
  "cycleId": "string",
  "labelIds": [
    "string"
  ],
  "number": 0,
  "identifier": "string",
  "repo": "string",
  "branch": "string",
  "prUrl": "string",
  "prState": "string",
  "prCheckState": "string",
  "createdAt": "string",
  "updatedAt": "string",
  "subStepProgress": {
    "total": 0,
    "done": 0,
    "blocked": 0,
    "ownerAgent": "string"
  },
  "possibleDuplicates": [
    {
      "id": "string",
      "identifier": "string",
      "title": "string",
      "status": "triage",
      "score": 0
    }
  ]
}

{
  "code": "CONFLICT",
  "message": "string",
  "hint": "string",
  "details": {
    "possibleDuplicates": [
      {
        "id": "string",
        "identifier": "string",
        "title": "string",
        "status": "triage",
        "score": 0
      }
    ]
  }
}