Skip to main content
For the complete documentation index for agents and LLMs, see llms.txt.

Run a Function Code Build with the REST APIBeta

Beta
This is coming — this page describes a feature that's still being rolled out and may not be available to you yet.

Send a JSON payload to a service that runs a function code build and get back its JSON result.

About This Task​

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.

If your service runs a pipeline instead, use Chat, Chat Stream, or Chat Completions. For details, see Choose a Chat Endpoint.

Prerequisites​

Call the Run Endpoint​

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.

To test the call, send a request with curl. Replace <API_HOST>, <WORKSPACE_NAME>, <DEPLOYMENT_ID>, and <API_KEY> with your own values, and replace the payload with the fields your function expects:

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?"}'

Validate the Payload Against an Input Schema​

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.

Match the Endpoint to the Build Type​

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.