Skip to main content
You’ve built and tested your prompts and workflows in the UI. Now it’s time to call them from your own product. The pattern is simple: trigger a run, wait for the webhook, fetch the result.

​
The integration flow

  1. Create a PromptJuggler API key in Settings
  2. Publish the prompt or workflow you want to call – only published versions are available via the API
  3. Trigger a run with a POST request, passing your inputs
  4. Store the run ID from the response
  5. Wait for the webhook telling you the run finished
  6. Fetch the result with a GET request using the run ID
That’s the whole loop.

​
Authentication

Every API request requires a Bearer token in the Authorization header: 
curl -X POST https://promptjuggler.com/api/v1/prompts/pr_my-prompt/production/runs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inputs": {"topic": "octopuses"}}'

​
Triggering runs

Runs are triggered by POST to either:
  • /api/v1/prompts/{slug}/{version}/runs – for prompt runs
  • /api/v1/workflows/{slug}/{version}/runs – for workflow runs
The version parameter accepts a version number (3), a tag (production), or __latest__ for the most recently published version. See Naming & Versioning for details. The request body includes:
FieldRequiredDescription
inputsYesKey-value pairs matching your prompt’s placeholders or workflow’s input nodes
threadNoThread ID to continue a conversation. Omit to start fresh
priorityNoonsite (highest), normal (default), or low
environmentNoEnvironment identifier (e.g. production, staging) for variable and webhook matching
metadataNoArbitrary key-value data attached to the run for your own tracking
The response returns a run ID and a thread ID. Store both – the run ID to fetch results, the thread ID if you want to continue the conversation in a follow-up call.

​
Priority

Runs triggered from the UI automatically get onsite priority. API runs default to normal. Use low for batch jobs or background processing where latency doesn’t matter. Higher-priority runs are processed first when the system is under load.

​
Webhooks

Instead of polling for completion, configure webhooks in Settings to receive a POST when a run finishes. Four webhook events are available:
EventFires when
promptrun.finishedA prompt run completes or fails
workflowrun.finishedA workflow run completes or fails
knowledgedocument.finishedA document finishes processing (chunking and embedding)
knowledgebase.finishedAll documents in a knowledge base are processed
Webhooks are signed with HMAC-SHA256 using your webhook secret. The signature arrives in the PromptJuggler-Signature header in the format t={timestamp},v1={signature}. To verify: recompute the HMAC over {timestamp}.{raw_request_body} and compare. Reject requests with timestamps outside your tolerance window to prevent replay attacks.

​
Environment matching

Both webhooks and environment variables use the same glob pattern matching. Tag a webhook URL with a pattern like prod* or staging, and it will only fire for runs whose environment field matches. A webhook with no environment tag fires for all runs.

​
Environment variables

Environment variables are injected into prompt and workflow runs automatically. Configure them in Settings. Two sources, applied in order:
  1. Global variables (set in Settings) – matched against the run’s environment field using glob patterns. A variable tagged prod* matches runs with environment production or prod-eu
  2. Per-request overrides – passed directly in the create-run API call. These take precedence over global variables with the same key
This lets you maintain a base set of credentials and configuration in Settings, while overriding specific values per request when needed – useful for example for multi-tenant setups where each of your customers needs different API keys or endpoints injected into the same workflow.

​
Knowledge Base management

The API supports managing knowledge base documents programmatically – handy when your users upload content through your product and you want their documents searchable by your AI behind the scenes.
  • Upload documents – POST files to /api/v1/knowledge-bases/{slug}/documents
  • Get a knowledge base – GET /api/v1/knowledge-bases/{slug} for status and document list
  • Get a document – GET /api/v1/knowledge-documents/{id} for processing status
  • Delete a document – DELETE /api/v1/knowledge-documents/{id}
Use the knowledgedocument.finished and knowledgebase.finished webhooks to know when uploaded documents are ready for search.

​
Full API Reference

See the API Reference for complete endpoint documentation with an interactive playground, request/response schemas, and code examples.