HTTP Endpoint Examples

See a worked example of an HTTP endpoint that reads, creates, and deletes issue links using GET, POST, and DELETE requests, with sample curl calls.

The following example demonstrates how to use an HTTP endpoint to manage issue links for a given Jira issue. The endpoint handles GET, POST, and DELETE requests to read, create, and remove issue links.

Manage issue links

Path:/issues/:issueKey/links

This endpoint reads issue links from Jira, adds new ones, and removes existing links depending on the HTTP method used.

import type { ApiRequest, ApiResponse } from "@scriptrunnerhq/types/api-endpoints";
import * as Issues from "@scriptrunnerhq/hapi/issues";
 
export default async function (request: ApiRequest): Promise<ApiResponse> {
  const { method, pathParams, body: requestBody } = request;
  const issueKey = pathParams.issueKey;
 
  if (!issueKey) {
    return {
      statusCode: 400,
      body: JSON.stringify({ error: "No work item key in the path" }),
    };
  }
 
  switch (method) {
    case "GET": {
      // Fetch linked work items from Jira
      const workItem = await Issues.getByKey(issueKey, { fields: ["issuelinks"] });
      return {
        statusCode: 200,
        body: JSON.stringify(workItem?.fields?.issuelinks ?? []),
      };
    }
 
    case "POST": {
      // Create a link
      const { targetIssue, linkType } = JSON.parse(requestBody ?? "{}");
      await Issues.linkIssue(issueKey, linkType, targetIssue);
      return { statusCode: 201, body: "" };
    }
 
    case "DELETE": {
      // Remove a link
      const { targetIssue, linkType } = JSON.parse(requestBody ?? "{}");
      await Issues.unlinkIssue(issueKey, linkType, targetIssue);
      return { statusCode: 204, body: "" };
    }
 
    default:
      return {
        statusCode: 405,
        body: JSON.stringify({ error: `Method ${method} not allowed` }),
      };
  }
}

Example requests

Copy the exact URL for your endpoint from the URL panel under Set the path. The examples below build the URL from shell variables, so set these once in your terminal session before you run them:

export APP_ID="17ea4f5c-0f4a-47dd-9f1d-5f286160a345"
export ENV_ID="<environment-id>"
export ISSUE_KEY="ISSUE-42"
export ACCESS_TOKEN="<access_token>"

Replace <environment-id> with the environment ID from your endpoint URL, and <access_token> with your access token.

GET: list linked work items

Retrieve all links for a given work item. Use this to inspect relationships between work items without querying Jira's full API directly.

curl -X GET "https://example.atlassian.net/gateway/api/svc/jira/apps/${APP_ID}_${ENV_ID}/api/issues/${ISSUE_KEY}/links" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Accept: application/json"

POST: create a link

Link two work items together by specifying a target work item and link type. Use this to programmatically define relationships from an external system or automation.

curl -X POST "https://example.atlassian.net/gateway/api/svc/jira/apps/${APP_ID}_${ENV_ID}/api/issues/${ISSUE_KEY}/links" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"targetIssue": "ISSUE-99", "linkType": "Relates"}'

DELETE: remove a link

Remove an existing link by providing the target work item and the link type. Use this to clean up stale or incorrect relationships without opening Jira manually.

curl -X DELETE "https://example.atlassian.net/gateway/api/svc/jira/apps/${APP_ID}_${ENV_ID}/api/issues/${ISSUE_KEY}/links" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"targetIssue": "ISSUE-99", "linkType": "Relates"}'