v2

latestOpenAPI 3.1.02026-07-2670186350.6 KB

calls

Function Call

The Call endpoint is a simple interface to issue a task to an LLM. It is a declarative interface with input and output schemas that supports text, image, audio inputs and outputs and is highly model agnostic.

post/call

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

Successful Response

span_idstring uuid required

The ID of the span of the call

messagestring nullable

Result of the task if the call does not use an output schema

cachedboolean nullable

True if the result was returned from a cached results

imagesstring[] nullable

The images generated by the call. Only available for image models. Depending on the configuration, the response can either be a list of image urls or a base64 encoded images.

usageobject nullable

The usage of the call split into input and output tokens as well as the total tokens and an optional breakdown of the input and output tokens.The input tokens are the tokens sent to the model and the output tokens are the tokens received from the model. The total tokens is the sum of input and output tokens.

costobject nullable

The cost in USD of the call split into total, generation and platform costs where total is the sum of generation and platform costs

Example response

{
  "message": "The sum of 1 and 3 is 4",
  "cached": true,
  "images": [
    "image_url"
  ],
  "usage": {
    "input_tokens": 25,
    "output_tokens": 972,
    "output_tokens_details": {
      "reasoning_tokens": 704
    },
    "total_tokens": 997
  },
  "cost": {
    "generation": 0.0001,
    "platform": 0.00001,
    "total": 0.00011
  }
}

All 70 operations