HTTP Endpoints

Request object

When an HTTP endpoint is called, your script receives an ApiRequest object as its first argument. This object contains everything you need to handle the request; the HTTP method, any path or query parameters, headers, and the request body.

import type { ApiRequest, ApiResponse } from "@scriptrunnerhq/types/api-endpoints";

A common pattern is to destructure the fields you need at the top of your script:

const { method, pathParams, queryParams, body } = request;

Response object

Your script must return an ApiResponse object. This tells ScriptRunner what HTTP status code and body to send back to the caller.

interface ApiResponse {
  statusCode: number
  body: string
}

• statusCode — a standard HTTP status code, such as 200 for success, 201 for created, 400 for a bad request, or 404 for not found. Use appropriate codes to make your endpoint behave like a well-formed API.
• body — must always be a string. If you want to return a JSON object, serialise it first with JSON.stringify().

A minimal valid response looks as follows:

return {
  statusCode: 200,
  body: JSON.stringify({ message: "Success" }),
};

Path patterns

The path you enter when creating an endpoint defines the URL route it responds to. Paths can include named parameters and wildcards, which are automatically extracted and made available in pathParams inside your script.

There are two types of dynamic segments:

• Named parameters ( :paramName) — match a single path segment and capture its value. For example, :issueKey in /issues/:issueKey/links captures the issue key from the URL.
• Wildcards ( :paramName*) — match one or more path segments and capture them as a single string. For example, :path* in /search/:path* captures everything after /search/.

Output and logging

When you run a script, the output panel shows:

• Anything logged with console.log(...)
• The final value returned by your script with return

Use console.log(...) for messages, intermediate values, or debugging, and include a return statement for the main result you want to display.

Activity history

Saved HTTP endpoints keep activity history (under Output), so you can review when they were run, and what the output was, making it easier to audit and troubleshoot.