Prompt Endpoints

Manage versioned prompt templates served as API endpoints. See Prompts for the end-user invocation API.

Endpoints

Operation	GraphQL
List endpoints	`prompt_endpoints(where: $whereConditions, limit: $limit, offset: $offset, order_by: {created_at: desc})`
Create endpoint	`insert_prompt_endpoints_one(object: {application_id, name, path, visibility, versioning_mode, default_model_id, settings, created_by, ...})`
Update endpoint	`update_prompt_endpoints_by_pk(pk_columns: {id: $endpointId}, _set: {name, path, visibility, versioning_mode, is_active, settings, ...})`

Endpoint fields

Field	Type	Description
`name`	string	Display name
`path`	string	URL slug for invocation (e.g., `generate-quiz` → `/v1/prompts/generate-quiz/invoke`)
`visibility`	string	`public` (any authenticated user), `private` (builder-role only), `unlisted` (accessible by URL, not listed)
`versioning_mode`	string	`manual`, `auto_increment`, or `semantic`
`default_model_id`	uuid	Reference to models table. Overridden by `settings.defaultModel`.
`is_active`	boolean	When `false`, invoke returns 404
`settings`	jsonb	Configuration object (see below)
`created_by`	uuid	Account ID of the creator

Settings object fields

The settings JSONB field configures the prompt behavior at invocation time. The invoke handler reads these fields directly.

Field	Type	Used by service	Description
`promptTemplate`	string	Yes	Required for invoke. Prompt text with `{{variable}}` placeholders.
`defaultModel`	string	Yes	Provider-prefixed model fallback (e.g., `openai/gpt-5.4`). Used when caller does not pass `model`.
`returnJsonFormat`	string (JSON)	Yes	JSON Schema string. Instructs the model to output structured JSON matching this schema and validates the output server-side.
`returnUsage`	boolean	Yes	When `false`, token usage is omitted from the response. Default: `true`.
`temperature`	number	Yes	Sampling temperature (0-2). Passed to the model at invoke time. Can be overridden per-request. Omit if your provider doesn’t support it.
`maxTokens`	number	Yes	Max output tokens. Passed to the model at invoke time. Can be overridden per-request via `max_tokens`.
`topP`	number	Yes	Top-p (nucleus) sampling. Passed to the model at invoke time. Omit if your provider doesn’t support it.

Current prompt invoke limitations

The invoke handler reads live prompt behavior from prompt_endpoints.settings.
Published prompt_versions are history/version records only; they are not read during invoke.
Tool-related request fields (tools, tool_choice, parallel_tool_calls) are not currently passed through by stored prompt invoke. Use /v1/responses directly if you need tool-enabled execution today.

Versions

Operation	GraphQL
List versions	`prompt_versions(where: {endpoint_id: {_eq: $endpointId}}, order_by: {created_at: desc})`
Create version	`insert_prompt_versions_one(object: {endpoint_id, version, prompt_text, tools, parameters, created_by})`
Publish version	`update_prompt_versions_by_pk(pk_columns: {id: $versionId}, _set: {is_published: true, published_at: "now()"})`
Get versioning mode	`prompt_endpoints_by_pk(id: $endpointId) { versioning_mode }`

Important: The invoke handler currently reads the prompt from endpoint.settings.promptTemplate, not from published versions in prompt_versions. Versions are tracked for history and can be promoted to the active template by copying prompt_text into settings.promptTemplate.

Operation	GraphQL
Add tag	`insert_prompt_tags_one(object: {endpoint_id, tag}, on_conflict: {constraint: prompt_tags_endpoint_tag_unique, update_columns: []})`
Remove tag	`delete_prompt_tags(where: {endpoint_id: {_eq: $endpointId}, tag: {_eq: $tag}})`
List tags	`prompt_tags(where: {endpoint_id: {_eq: $endpointId}})`