Prompt Endpoints

PickLayer allows you to define reusable prompt templates that can be invoked with variables. This enables consistent, versioned prompts across your application.

Invoke a Prompt

POST /v1/prompts/:slug/invoke


{
  "model": "openai/gpt-4o-mini",
  "variables": { "company": "Acme", "tone": "friendly" }
}

Request Parameters

Field	Type	Required	Description
`model`	string	No	Provider-prefixed model override (e.g., `openai/gpt-4o`). Falls back to the endpoint’s `settings.defaultModel`, then `default_model_id`.
`variables`	object	No	Key-value pairs to substitute into the prompt template. Variables use `{{variableName}}` syntax in the template.
`stream`	boolean	No	Enable streaming response (default: false)
`temperature`	number	No	Sampling temperature override (0-2). Falls back to `settings.temperature`. Not all providers support this.
`max_tokens`	number	No	Max output tokens override. Falls back to `settings.maxTokens`. Also accepts `max_output_tokens`.
`top_p`	number	No	Top-p sampling override. Falls back to `settings.topP`. Not all providers support this.
`tools`	array	No	Not currently passed through by stored prompt invoke. Use `/v1/responses` directly if you need tool-enabled execution today.
`tool_choice`	string or object	No	Not currently passed through by stored prompt invoke.
`parallel_tool_calls`	boolean	No	Not currently passed through by stored prompt invoke.

Response

The response format depends on the upstream model provider. When using OpenAI models via the Responses API, the response shape is:


{
  "id": "resp_abc123",
  "object": "response",
  "model": "gpt-5.4",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [
        { "type": "output_text", "text": "..." }
      ]
    }
  ],
  "output_text": "...",
  "usage": {
    "input_tokens": 256,
    "output_tokens": 424,
    "total_tokens": 680
  }
}

The output_text field at the top level contains the full text output for convenience.

Endpoint Configuration

Prompt endpoints are configured via the settings JSON field. These settings control the prompt template, model defaults, output validation, and response behavior.

Settings Fields

Field	Type	Description
`promptTemplate`	string	Required. The prompt text with `{{variable}}` placeholders. Variables are substituted at invoke time from the `variables` request parameter.
`defaultModel`	string	Provider-prefixed model to use when the caller does not specify one (e.g., `openai/gpt-5.4`). Falls back to the endpoint’s `default_model_id` column.
`returnJsonFormat`	string (JSON)	JSON Schema string. When set, the model is instructed to output structured JSON matching this schema (via `json_schema` response format), and the server validates the output.
`temperature`	number	Sampling temperature (0-2). Passed to the model at invoke time. Can be overridden per-request. Not all providers support this — omit from settings if your provider rejects it.
`maxTokens`	number	Max output tokens. Passed to the model at invoke time. Can be overridden per-request via `max_tokens`.
`topP`	number	Top-p (nucleus) sampling. Passed to the model at invoke time. Not all providers support this — omit from settings if your provider rejects it.
`returnUsage`	boolean	When `false`, token usage is tracked internally but not included in the API response. Default: `true`.

Current Source Of Truth

The invoke handler currently reads the live prompt configuration from prompt_endpoints.settings.

settings.promptTemplate is the prompt text used at invoke time.
settings.defaultModel and default_model_id control model fallback.
settings.returnJsonFormat, temperature, maxTokens, topP, and returnUsage are also read from the endpoint row.

prompt_versions are historical/versioning records, but they are not the runtime source of truth today. In particular, any prompt_versions.tools content is not applied during invoke.

Example Settings


{
  "promptTemplate": "Generate {{count}} quiz questions in {{language}} at {{cefr_level}} level about:\n{{content}}",
  "defaultModel": "openai/gpt-5.4",
  "temperature": 0.7,
  "maxTokens": 8192,
  "returnJsonFormat": "{\"type\":\"array\",\"items\":{\"type\":\"object\",\"required\":[\"id\",\"question\",\"options\"],\"properties\":{\"id\":{\"type\":\"string\"},\"question\":{\"type\":\"string\"},\"options\":{\"type\":\"array\",\"items\":{\"type\":\"string\"}}}}}",
  "returnUsage": true
}

Prompt Template Syntax

Templates support {{variableName}} placeholders (double curly braces). When a prompt is invoked, each placeholder is replaced with the corresponding value from the variables object. Unmatched variables are replaced with empty strings.


You are a {{role}} helping with {{task}}.

The user's name is {{name}} and they speak {{language}}.

Invoked with {"variables": {"role": "teacher", "task": "vocabulary", "name": "Maria", "language": "French"}}.

Endpoint Fields

When creating or updating prompt endpoints via the Management API, the following fields are available:

Field	Type	Description
`name`	string	Display name for the endpoint
`path`	string	URL slug used in the invoke URL (e.g., `generate-quiz` becomes `/v1/prompts/generate-quiz/invoke`)
`visibility`	string	Access control: `public` (any authenticated user), `private` (builder-role only), `unlisted` (accessible by URL but not listed)
`versioning_mode`	string	Version management: `manual` (v1, v2, etc.), `auto_increment`, or `semantic`
`default_model_id`	uuid	Reference to a model in the models table. Overridden by `settings.defaultModel` if set.
`settings`	jsonb	Configuration object (see Settings Fields above)
`is_active`	boolean	When `false`, the endpoint returns 404 on invoke

Key Notes

Model resolution order: request.model > settings.defaultModel > default_model_id. At least one must be set or the invoke returns 400.
Variable validation: Variables detected in the template ({{var}}) are auto-parsed. Missing required variables cause the placeholder to be replaced with an empty string (no error).
Structured output: When returnJsonFormat is set, the model is instructed to output JSON matching the schema (via OpenAI’s json_schema response format). The server also validates the output post-hoc. This ensures the response is always valid JSON matching your expected structure.
Parameter precedence: Request-level params (temperature, max_tokens, top_p) override endpoint settings. Settings override nothing (they are defaults only).
Tool use today: Stored prompt invoke is currently a prompt wrapper around /v1/responses, but it does not yet pass through tools, tool_choice, or parallel_tool_calls. Use /v1/responses directly if you need tool-enabled execution right now.
Provider format: Use the same provider-prefixed form as other AI endpoints (e.g., openai/gpt-5.4, openrouter/anthropic/claude-sonnet-4-20250514).

Example


curl -X POST "https://api.picklayer.dev/api/org/acme/app/myapp/v1/prompts/welcome-email/invoke" \
  -H "Authorization: Bearer <JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.4",
    "variables": {
      "customer_name": "John",
      "product": "Premium Plan"
    }
  }'