> ## Documentation Index
> Fetch the complete documentation index at: https://docs.promptjuggler.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration Guide

> API keys, webhooks, environment variables – everything you need to go live.

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](https://promptjuggler.com/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:

```bash theme={null}
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](/concepts/naming-and-versioning) for details.

The request body includes:

| Field         | Required | Description                                                                             |
| ------------- | -------- | --------------------------------------------------------------------------------------- |
| `inputs`      | Yes      | Key-value pairs matching your prompt’s placeholders or workflow’s input nodes           |
| `thread`      | No       | Thread ID to continue a conversation. Omit to start fresh                               |
| `priority`    | No       | `onsite` (highest), `normal` (default), or `low`                                        |
| `environment` | No       | Environment identifier (e.g. `production`, `staging`) for variable and webhook matching |
| `metadata`    | No       | Arbitrary 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](https://promptjuggler.com/settings) to receive a POST when a run finishes. Four webhook events are available:

| Event                        | Fires when                                              |
| ---------------------------- | ------------------------------------------------------- |
| `promptrun.finished`         | A prompt run completes or fails                         |
| `workflowrun.finished`       | A workflow run completes or fails                       |
| `knowledgedocument.finished` | A document finishes processing (chunking and embedding) |
| `knowledgebase.finished`     | All 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](https://promptjuggler.com/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](/api/overview) for complete endpoint documentation with an interactive playground, request/response schemas, and code examples.