Prism Server
Prism Server exposes registered Prism configurations through an OpenAI-compatible API for use by chat interfaces and other clients.
How It Works#
Prism Server exposes a subset of the OpenAI Chat Completions API. It provides a model list and text completions backed by application-owned Prism configuration. Client support depends on whether the client can use this request subset.
Setting Up Prism Server#
Protect the endpoints before enabling them
The default prism_server.middleware list is empty. Enabling the server without adding authentication and authorization exposes endpoints that spend your provider credentials. Apply your application's authentication, access policy and rate limits before making these routes reachable. The api middleware group alone does not authenticate callers.
1. Enable Prism Server#
Set PRISM_SERVER_ENABLED=true in the server environment and update the existing prism_server entry in config/prism.php. For an application already configured to authenticate API tokens with Sanctum:
'prism_server' => [ // The middleware that will be applied to the Prism Server routes. 'middleware' => ['auth:sanctum', 'throttle:60,1'], 'enabled' => env('PRISM_SERVER_ENABLED', false), ],
2. Register Your Prisms#
To make your Prism models available through the server, you need to register them. This is typically done in a service provider, such as AppServiceProvider:
use Prism\Prism\Facades\Prism; use Prism\Prism\Enums\Provider; use Prism\Prism\Facades\PrismServer; use Illuminate\Support\ServiceProvider; class AppServiceProvider extends ServiceProvider { public function boot(): void { PrismServer::register( 'my-custom-model', fn () => Prism::text() ->using(Provider::Anthropic, 'claude-sonnet-5-5') ->withSystemPrompt('You are a helpful assistant.') ); } }
Clients use the registered name my-custom-model. Keep credentials and generation controls in the registered factory or server configuration, and authorize which callers may use it.
Using Prism Server#
Once set up, Prism Server exposes two main endpoints:
Chat Completions#
To generate text using your registered Prism models:
curl -X POST "https://your-app.example/prism/openai/v1/chat/completions" \ -H "Authorization: Bearer $PRISM_SERVER_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "model": "my-custom-model", "messages": [ {"role": "user", "content": "Hello, who are you?"} ] }'
Streaming#
Send "stream": true in the same JSON body and use curl --no-buffer to receive SSE. The endpoint forwards text deltas as chat.completion.chunk objects and terminates with data: [DONE]. It does not forward Prism tool, approval, citation, thinking, step or final usage events. The streamed model field is unknown. Expose asEventStreamResponse() from an authenticated application route when your client needs Prism's complete event stream.
List Available Models#
To get a list of all registered Prism models:
curl "https://your-app.example/prism/openai/v1/models" \ -H "Authorization: Bearer $PRISM_SERVER_TOKEN"
Integration with Open WebUI#
Configure an OpenAI-compatible client with the base URL https://your-app.example/prism/openai/v1, its application-issued API token and a registered model name. The curl examples assume that token is stored in the client environment as PRISM_SERVER_TOKEN.
Supported request fields#
The controller reads model, messages and stream. Always include a message array. Client fields such as temperature, max_tokens, top_p, tools, tool_choice and response_format are ignored and do not override the registered builder. A client cannot add a tool, redefine one or choose which tool the model calls.
Message roles are limited to user, assistant and system; a tool role is refused. An assistant message that carries tool_calls (or a legacy function_call) is refused the same way, with 422 invalid_messages; its error message names the position in your messages array, for example messages[3]: an assistant message carrying tool calls cannot be replayed; a returned tool call ends the conversation. Other unreadable messages get the generic message. Unknown top-level fields are ignored. User content can carry supported OpenAI-style text/image parts, while assistant and system content are mapped as text. Use Prism directly for client-tool continuation and approvals.
The non-streaming endpoint serializes finish_reason as tool_calls when it returns tool calls, and as stop otherwise; it does not preserve Prism's refusal, truncation or other finish reasons. Use Prism directly when your workflow needs those distinctions.
Returning tool calls to the caller#
A registered prism can end a turn in a tool call that the caller reads instead of the server running it. Use this when the client needs a structured signal, for example "the interview is over, here is the result", while ordinary turns stay plain text.
Mark the tool with clientExecuted() on the registered prism. Tools with a handler keep running on the server as before and are never shown to the caller:
use Prism\Prism\Facades\Prism; use Prism\Prism\Facades\PrismServer; use Prism\Prism\Facades\Tool; PrismServer::register( 'interview', fn () => Prism::text() ->using('openai', 'gpt-5') ->withSystemPrompt('Interview the user. When you have everything, call business_case_report.') ->withMaxSteps(5) ->withTools([ Tool::as('lookup_pricing') ->for('Look up a price') ->withStringParameter('plan', 'The plan name') ->using(fn (string $plan): string => (string) config("pricing.{$plan}", "unknown")), Tool::as('business_case_report') ->for('Report the finished business case') ->withStringParameter('problem', 'The problem') ->withStringParameter('report', 'The report') ->clientExecuted(), ]) );
When the model calls business_case_report, the run stops and the response carries the call in the OpenAI Chat Completions shape:
{ "id": "resp_123", "object": "chat.completion", "created": 1763400000, "model": "gpt-5", "usage": { "prompt_tokens": 60, "completion_tokens": 13, "total_tokens": 73 }, "choices": [{ "index": 0, "message": { "content": "Thanks, that is everything.", "role": "assistant", "tool_calls": [{ "id": "call_abc123", "type": "function", "function": { "name": "business_case_report", "arguments": "{\"problem\":\"churn\",\"report\":\"...\"}" } }] }, "finish_reason": "tool_calls" }] }
argumentsis a JSON string,"{}"when the call has none.contentisnullwhen the model wrote no text beside the call.finish_reasonistool_callsexactly whentool_callsis present.usagecovers the whole turn, including earlier steps that ran server tools.idis the provider's tool call id, or a generatedcall_…id when the provider sent none.
The server never runs a returned tool. If the model calls a server tool and a returned tool in the same step, nothing from that step runs: the response carries only the returned calls, and the server tool is neither executed nor shown. Server tools called in earlier steps run as usual.
The exchange is one-way. The client does not send tool results back, and a tool message or an assistant message with tool_calls in a later request is refused. Send the next turn as a fresh request with the history as user, assistant and system messages.
Streaming is not available for a prism that has returned tools. A request with "stream": true is refused with 400 stream_not_supported before the provider is called.
Errors#
Errors use the OpenAI shape, {"error":{"message":"...","type":"...","code":...}}, with a fixed message. An exception's own message is never sent to the caller:
| Failure | Status | code |
|---|---|---|
| Unknown model | 404 | model_not_found |
Messages that cannot be read, including tool messages and assistant tool_calls |
422 | invalid_messages |
"stream": true for a prism with returned tools |
400 | stream_not_supported |
| Anything else, including provider errors | 500 | null (type is server_error) |
For a 500, the exception is reported through your application's exception handler, so it reaches your logs with its full detail. Requests that fail validation keep Laravel's validation response (422).
To decide the response yourself, register a renderer. Return a response to use it, or null to keep the default:
use Prism\Prism\Facades\PrismServer; PrismServer::renderErrorsUsing(function (Throwable $e) { return response()->json([ 'error' => ['message' => 'The assistant is unavailable. Try again later.', 'type' => 'server_error'], ], 503); });
Whatever your renderer returns is sent as it is, so do not put exception messages in it unless your callers may see them. If the renderer throws, Prism uses the default response and reports both exceptions.
Streaming failures can occur after HTTP headers have been sent and are not converted by that outer error handler. A stream closing without its expected terminator is not successful completion.
Adding Middleware#
You can add middleware to the Prism Server routes by setting the middleware option in your config/prism.php file:
// For an application configured to authenticate API tokens with Sanctum: return ['prism_server' => [ 'middleware' => ['auth:sanctum'], ]];