Sign in

v2

latestOpenAPI 3.1.02026-07-2670186350.6 KB
calls

Function Stream

Stream a function call execution in real-time using Server-Sent Events (SSE).

This endpoint provides continuous streaming of function execution results, supporting both unstructured text streaming and structured JSON streaming with precise field tracking.

Streaming Modes

Text Mode (no output_schema):

  • Streams incremental text content via the delta field
  • chunk_type will be "text"
  • Best for conversational AI, creative writing, open-ended responses

Structured Mode (with output_schema):

  • Streams structured JSON with precise field tracking via json_path
  • chunk_type will be "json"
  • Enables real-time UI updates by showing which schema field is being populated
  • Perfect for forms, dashboards, structured data display

JSON Path Feature

When using output_schema, each streaming chunk includes a json_path field showing exactly which field in your schema is being populated:

  • response.summary → Top-level string field
  • response.people[0].name → Name of first person in array
  • response.people[1].role → Role of second person
  • response.metadata.created_at → Nested object field

This enables precise UI updates where you can route streaming content to specific components based on the path, creating responsive real-time interfaces.

Response Structure

Each Server-Sent Event contains:

  • id: Optional event identifier
  • event: Optional event type (typically "message")
  • data: StreamingChunk with the actual streaming content
  • retry: Optional retry interval for reconnection

The StreamingChunk data payload varies by mode:

Text Mode:

  • delta: Incremental text content
  • span_id: Execution span ID (first chunk)
  • chunk_type: "text"

Structured Mode:

  • delta: Actual field values being streamed
  • json_path: Dot-notation path to current field
  • span_id: Execution span ID (first chunk)
  • chunk_type: "json"

Examples

Text streaming events:

data: {"span_id": "123e4567-e89b-12d3-a456-426614174000"}
data: {"delta": "Hello", "chunk_type": "text"}
data: {"delta": " world", "chunk_type": "text"}

Structured streaming events:

data: {"span_id": "123e4567-e89b-12d3-a456-426614174000"}
data: {"delta": "John", "json_path": "response.name", "chunk_type": "json"}
data: {"delta": " Doe", "json_path": "response.name", "chunk_type": "json"}
data: {"delta": "Engineer", "json_path": "response.role", "chunk_type": "json"}
post/call/stream

Request body

namestring required

Provide a unique name of the task. A function with this name will be created in the project. Functions configuration is overridden by the request parameters.

instructionsstring nullable

Optionally provide an instruction for the model to complete the task. Recommended to be concise and to the point

input_schemaobject nullable

Optionally provide an input schema for the task. Can preferably include field descriptions to allow the model to reason about the input variables. Schema is validated against the input data and issues an error if it does not match. With the Opper SDKs you can define these schemas through libraries like Pydantic and Zod. For schemas with definitions, prefer using '$defs' and '#/$defs/...' references.

output_schemaobject nullable

Optionally provide an output schema for the task. Response is guaranteed to match the schema or throw an error. Can preferably include field descriptions to allow the model to reason about the output variables. With the Opper SDKs you can define these schemas through libraries like Pydantic and Zod. For schemas with definitions, prefer using '$defs' and '#/$defs/...' references.

Streaming with output_schema: When used with streaming endpoints, enables precise field tracking via json_path. Each streaming chunk includes the exact schema field being populated (e.g., 'response.people[0].name'), allowing real-time UI updates by routing content to specific components.

{"stackTrail":"components:schemas:app__api__public__v2__function_call__CallFunctionRequest:properties:input:anyOf","oasType":"schema","type":"unknown","title":"Input","description":"Optionally provide input data as context to complete the task. Could be a text, image, audio or a combination of these.","example":{"x":4,"y":5},"nullable":true}
parent_span_idstring uuid nullable

Optionally provide the parent span ID to add to the call event. This will automatically tie the call to a parent span in the UI.

tagsobject nullable

Optionally provide a list of tags to add to the call event. Useful for being able to understand aggregate analytics on some dimension.

Example request

{
  "name": "add_numbers",
  "instructions": "Calculate the sum of two numbers",
  "input_schema": {
    "properties": {
      "x": {
        "title": "X",
        "type": "integer"
      },
      "y": {
        "title": "Y",
        "type": "integer"
      }
    },
    "required": [
      "x",
      "y"
    ],
    "title": "OpperInputExample",
    "type": "object"
  },
  "output_schema": {
    "properties": {
      "sum": {
        "title": "Sum",
        "type": "integer"
      }
    },
    "required": [
      "sum"
    ],
    "title": "OpperOutputExample",
    "type": "object"
  },
  "input": {
    "x": 4,
    "y": 5
  },
  "examples": [
    {
      "comment": "Adds two numbers",
      "input": {
        "x": 1,
        "y": 3
      },
      "output": {
        "sum": 4
      }
    }
  ],
  "parent_span_id": "123e4567-e89b-12d3-a456-426614174000",
  "tags": {
    "project": "project_456",
    "user": "company_123"
  }
}

Response

Server-Sent Events stream of function execution chunks