Connect to a Published ServiceBeta
Call a published service from your own app, from the built-in chat, from an OpenAI-compatible chat client, or from a Model Context Protocol (MCP) client. The service endpoint stays the same when you publish a new pipeline version.
About This Task
A service is a stable endpoint that runs the pipeline version you published in Gateway. You authenticate with a workspace API key, or with OAuth and dynamic client registration (DCR) when that option is enabled, and send queries with one of the chat APIs:
- Chat returns one JSON response when the run finishes. Conversation history comes from a search session.
- Chat Stream uses the same conversation model and sends the answer as Server-Sent Events (SSE) while it is generated.
- Chat Completions uses the OpenAI Chat Completions contract, so OpenAI-compatible clients can call the service.
If the service runs a function code build, call it with Run instead. A function takes a free-form JSON payload and returns a JSON result. For details, see Run a Function Code Build.
You can also send a query in the built-in chat by sharing a prototype link, or expose the service on the workspace MCP server and call it as a tool.
Prerequisites
- A service with a pipeline version published to it. For details, see Create a Service and Publish a Pipeline to a Service.
- A way to authenticate. Use a workspace API key, or OAuth with dynamic client registration (DCR) when it is enabled. For API keys, see Generate API Keys.
- Read permission for services. For details, see User Roles and Permissions.
Get the Service Endpoint
- In Haystack Enterprise Platform, click Gateway and open the service you want to call.
- Click Connect.
- Under API format, select the format you want to use. Select Completions API for OpenAI-compatible clients.
- In the Endpoint card, copy the URL. You don't need to update it in your app when you publish a new pipeline version.
Authenticate with a workspace API key as a Bearer token in the Authorization header. To create or manage keys from this page, click Manage API keys. Store API keys in a secrets manager and never expose them in client-side code.
If OAuth with DCR is enabled, a client can sign in with OAuth instead of an API key. The client registers itself and completes the sign-in.
Choose a Chat Endpoint
To pick between the Chat, Chat Stream, and Chat Completions endpoints, see Choose a Chat Endpoint.
Run a Function Code Build
Use Run when the active revision of your service is a function code build, which means a revision pushed with a code bundle whose entrypoint kind is function. Run lets your app send any JSON object to the function and get back whatever the function returns. It doesn't use search sessions or conversation history.
Send a POST request to the service's run endpoint, which sits next to its chat and search endpoints:
POST /workspaces/{workspace_name}/deployments/{deployment_id}/run
The request body is a JSON object, and the platform passes it to the function as its payload. The response wraps the function's return value:
{"result": "<whatever the function returned>"}
The result value can be any JSON value. Authenticate the same way as for the other endpoints, with a workspace API key as a Bearer token.
If the revision stores an input schema, the platform validates your payload against it before it runs the function. The code build tooling computes the input schema when the revision is pushed. If the payload doesn't match, the request fails with status 422 and a message that describes the mismatch, so you can fix the payload and send it again.
Run and the other endpoints work with different build types:
- Run returns status 400 if the active revision isn't a function code build, for example a pipeline defined in YAML. The error message names the endpoint to use instead, such as Chat.
- Search and Chat return status 400 for a function code build. The error message points you to Run.
The platform records each revision's build type in the artifact_type field of the deployment revision response: yaml for a pipeline defined in the revision configuration, and code_bundle for a code build.
To test the call, send a request with curl:
curl -X POST "https://<API_HOST>/api/v1/workspaces/<WORKSPACE_NAME>/deployments/<DEPLOYMENT_ID>/run" \
-H "Authorization: Bearer <API_KEY>" \
-H "Content-Type: application/json" \
-d '{"query": "What is Haystack?"}'
Replace the payload with the fields that your function expects.
Connect OpenAI-Compatible Clients
You can point an OpenAI-compatible chat client at Chat Completions and run the service as a hosted model. Thunderbolt and Open WebUI are two examples. Other clients that use the OpenAI Chat Completions API work the same way.
In the client, set the base URL to the Chat Completions endpoint for your workspace and choose the model ID for the service. Authenticate with a workspace API key, or with OAuth and DCR when the client supports it and DCR is enabled. If the client can fetch models, use List Models so it can discover the services in the workspace. Follow the client's own setup for where those values go. For a walkthrough of Open WebUI, Thunderbolt, and the Vercel AI SDK, see Tutorial: Connecting OpenAI-Compatible Clients to a Service. Chat Completions doesn't support client-side tool calling, so a client can't pass its own tools to the service.
Use the Chat Interface
You can send a query to a service in the built-in chat, without calling the API yourself.
- In Haystack Enterprise Platform, click Gateway and open the service.
- On Overview, click Share prototype.
- Generate a link and open it. The page is a chat where you, or anyone you send the link to, can query the service.
To set the link expiration, require login, turn on filters, and apply your logo and colors, see Share a Service.
Use the Workspace MCP Server
You can expose a service as a tool on your workspace MCP server, so MCP-capable AI assistants, such as Claude Desktop or Cursor, can call the service directly. Using a service as an MCP tool is recommended for production because the service endpoint stays stable when you publish a new pipeline version.
To turn on Use as MCP tool for a service, see Manage a Service. To connect an MCP client to the workspace server, see Use Your Pipelines as MCP Tools.
What To Do Next
- Share a prototype so people can query the service in the chat.
- Test the service from Gateway before you add it to an app.
- Trace a query when you need to debug a run.
Related Information
Was this page helpful?