POST
/
v1
/
prompt_engine
/
run
import { JigsawStack } from "jigsawstack";

const jigsaw = JigsawStack({ apiKey: "your-api-key" });

const response = await jigsaw.prompt_engine.run_direct({
  "prompt": "Tell me a story about {about}",
  "inputs": [
        {
              "key": "about",
              "optional": false,
              "initial_value": "Leaning Tower of Pisa"
        }
  ],
  "return_prompt": "Return the result in a markdown format",
  "prompt_guard": [
        "sexual_content",
        "defamation"
  ],
  "input_values": {
        "about": "Santorini"
  }
})
{
  "success": true,
  "result": "Okay, here's a story about Santorini, set with the current ISO time in mind:\n\n***\n\nThe Aegean wind, a salty whisper, tugged at Eleni's white linen dress as she stood on the caldera's edge. The time, according to her phone, was 2025-06-09T23:03:03.049Z. Almost midnight. The sky, a deep indigo velvet, was studded with a million diamonds, mirroring the twinkling lights of Oia clinging precariously to the cliff face below.\n\nEleni wasn't a tourist. She was a descendant of the islanders who had rebuilt their lives after the devastating volcanic eruption millennia ago. Her family had been fishing the Aegean for generations, their lives intertwined with the rhythm of the sea and the stoic beauty of Santorini.\n\nTonight, though, she wasn't thinking of fishing. She was thinking of her grandmother, Yaya Irini, who had passed away just a few weeks prior. Yaya Irini had been the keeper of the island's stories, the one who remembered the old ways, the whispers of the gods, and the secrets hidden within the volcanic rock.\n\nYaya Irini had always told Eleni that the caldera held more than just water. It held memories. She believed that on certain nights, when the moon was just right and the wind carried the scent of thyme and salt, you could hear the echoes of the past.\n\nEleni closed her eyes, breathing deeply. The air was thick with the scent of the sea and the faint, earthy aroma of the volcanic soil. She tried to focus, to listen for the whispers Yaya Irini had spoken of.\n\nSuddenly, a faint melody drifted on the wind. It was a haunting, melancholic tune played on a bouzouki, a sound Eleni hadn't heard in years. It was the music her grandfather used to play, the music that always made Yaya Irini smile.\n\nTears welled in Eleni's eyes. She opened them, searching the darkness for the source of the music. There was no one there. Just the wind, the stars, and the silent, watchful caldera.\n\nThen, she saw it. A faint, shimmering light rising from the water below. It pulsed gently, like a heartbeat, and as it grew brighter, Eleni could almost make out figures dancing in the ethereal glow. They were dressed in clothes from a bygone era, their faces illuminated by the otherworldly light.\n\nEleni knew, with a certainty that settled deep in her soul, that she was witnessing a memory. A fragment of the past, brought to life by the magic of the island and the love of her grandmother.\n\nThe music swelled, the dancing intensified, and for a brief, fleeting moment, Eleni felt connected to something ancient and profound. She felt the weight of history, the resilience of her people, and the enduring power of love.\n\nAs quickly as it had appeared, the light began to fade. The music softened, the dancing figures dissolved into the darkness, and the caldera returned to its silent vigil.\n\nEleni stood there, breathless, her heart pounding in her chest. The time was still 2025-06-09T23:03:03.049Z, but for Eleni, time had stood still. She had glimpsed the past, and in doing so, she had found a renewed sense of hope for the future. She knew that Yaya Irini's stories would live on, not just in her memory, but in the very heart of Santorini. And she knew that she, Eleni, would be the one to keep them alive.\n",
  "message": "It is recommended to store the prompt engine and execute it using the ID rather than running it directly for the best performance and reliability. Learn more: https://jigsawstack.com/docs/api-reference/prompt-engine/create",
  "_usage": {
        "input_tokens": 68,
        "output_tokens": 877,
        "inference_time_tokens": 5633,
        "total_tokens": 6578
  }
}
Run Prompt Direct is ideal for one-time prompt usage.

For prompts that will be used multiple times, it is recommended to first Create a Prompt and then Run the Prompt for better reliability.

x-api-key
string
required

Your JigsawStack API key

Body

prompt
string
required

The prompt. Maximum character limit is 500000. Prompt supports dynamic inputs. See example below.

inputs
array<object>

The prompt inputs. See example below.

return_prompt
string | array | object

How the prompt result should be returned or formatted. See examples below

prompt_guard
array<string>

Include this to guard against unsafe inputs from users. Supported values:

  • defamation
  • privacy
  • hate
  • sexual_content
  • elections
  • code_interpreter_abuse
  • indiscrimate_weapons
  • specialized_advice
input_values
object

Key-value pair for dynamic prompt variables. Each input value has a 500000 character limit

stream
boolean

If set, partial message chunk will be sent.

use_internet
boolean

Include this to allow prompt engine to use the internet.

Sample Prompt Payload

  • String return_prompt
{
    prompt: "Tell me a story about {about}",
    inputs: [
      {
        key: "about",
        optional: false,
      },
    ],
    return_prompt: "Return the result in a markdown format",
    "prompt_guard": ["sexual_content", "defamation"]
    "input_values": {
      "about": "Santorini",
    }
  }
  • Array<object> return_prompt

{
    prompt: "Tell me a story about {about}",
    inputs: [
      {
        key: "about",
        optional: false,
        initial_value: "Leaning Tower of Pisa",
      },
    ],
    return_prompt: [{ excerpt: "short story text", summary: "summary of story" }],
    "prompt_guard": ["sexual_content", "defamation"],
    "input_values": {
      "about": "Santorini",
    }
  }
  • Object return_prompt
{
    prompt: "Tell me a story about {about}",
    inputs: [
      {
        key: "about",
        optional: false,
        initial_value: "Leaning Tower of Pisa",
      },
    ],
    return_prompt: { excerpt: "short story text", summary: "summary of story" },
    "prompt_guard": ["sexual_content", "defamation"],
    "input_values": {
      "about": "Santorini",
    }
  }

Response

success
boolean

Indicates whether the call was successful.