> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opper.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Call

> Execute a function by name (passed in the request body). If no cached script exists, one is generated automatically.



## OpenAPI

````yaml post /v3/call
openapi: 3.1.0
info:
  description: Schema-driven generative API that orchestrates LLM-powered workflows.
  title: Task API
  version: 3.0.0
servers:
  - description: Production
    url: https://api.opper.ai
  - description: Local development
    url: http://localhost:8080
security:
  - BearerAuth: []
tags:
  - description: Schema-driven function management and execution
    name: Functions
  - description: OpenAI-compatible chat completions
    name: Chat
  - description: OpenAI Responses API compatible endpoint
    name: Responses
  - description: Google-compatible interactions endpoint
    name: Interactions
  - description: Model registry and capabilities
    name: Models
  - description: Synchronous image generation
    name: Images
  - description: Text-to-speech and speech-to-text
    name: Audio
  - description: Asynchronous video generation
    name: Videos
  - description: Reusable file storage for media inputs and generated outputs
    name: Files
  - description: Async generation status and downloads
    name: Artifacts
  - description: OpenAI-compatible embeddings
    name: Embeddings
  - description: Recorded HTTP request/response generations
    name: Generations
  - description: System health and status
    name: System
  - description: Roundtable endpoint — fan out a query to multiple LLMs and combine results
    name: Roundtable
  - description: Web search, fetch, and other utility tools
    name: Tools
  - description: Caller identity, credits, and usage
    name: Account
paths:
  /v3/call:
    post:
      tags:
        - Functions
      summary: Call function by name
      description: >-
        Execute a function by name (passed in the request body). If no cached
        script exists, one is generated automatically.
      operationId: call
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CallRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunResponse'
          description: Successful response
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PendingResponse'
          description: >-
            Accepted – async operation pending. Poll the status URL in
            meta.pending_operations.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Bad request
        '401':
          description: Unauthorized - missing or invalid API key
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal server error
      x-codeSamples:
        - lang: Python
          label: Python
          source: |-
            result = opper.call(
                "get_capital",
                instructions="Return the capital of the given country.",
                input={"country": "Sweden"},
                output_schema=CapitalOutput,
            )

            print(result.data.capital)
        - lang: TypeScript
          label: TypeScript
          source: |-
            import { z } from "zod";
            import { Opper } from "opperai";

            const opper = new Opper();

            const result = await opper.call("get_capital", {
              instructions: "Return the capital of the given country.",
              input: { country: "Sweden" },
              output_schema: z.object({
                capital: z.string(),
                population: z.number().optional(),
              }),
            });

            console.log(result.data.capital);
components:
  schemas:
    CallRequest:
      properties:
        guard:
          properties:
            input:
              items:
                properties:
                  action:
                    type: string
                  applies_to:
                    type: string
                  check:
                    type: string
                  custom_patterns:
                    items:
                      type: string
                    type: array
                  engine:
                    type: string
                  kind:
                    type: string
                  model:
                    type: string
                  name:
                    type: string
                  patterns:
                    items:
                      properties:
                        name:
                          type: string
                        regex:
                          type: string
                      required:
                        - regex
                      type: object
                    type: array
                  presets:
                    items:
                      type: string
                    type: array
                  prompt:
                    type: string
                  replacement:
                    type: string
                  rule_id:
                    type: string
                  rule_name:
                    type: string
                  scope:
                    properties:
                      functions:
                        items:
                          type: string
                        type: array
                      kind:
                        type: string
                    required:
                      - kind
                    type: object
                  scope_type:
                    type: string
                  type:
                    type: string
                type: object
              type: array
            output:
              items:
                properties:
                  action:
                    type: string
                  applies_to:
                    type: string
                  check:
                    type: string
                  custom_patterns:
                    items:
                      type: string
                    type: array
                  engine:
                    type: string
                  kind:
                    type: string
                  model:
                    type: string
                  name:
                    type: string
                  patterns:
                    items:
                      properties:
                        name:
                          type: string
                        regex:
                          type: string
                      required:
                        - regex
                      type: object
                    type: array
                  presets:
                    items:
                      type: string
                    type: array
                  prompt:
                    type: string
                  replacement:
                    type: string
                  rule_id:
                    type: string
                  rule_name:
                    type: string
                  scope:
                    properties:
                      functions:
                        items:
                          type: string
                        type: array
                      kind:
                        type: string
                    required:
                      - kind
                    type: object
                  scope_type:
                    type: string
                  type:
                    type: string
                type: object
              type: array
          type: object
        input:
          description: Any value
        input_schema:
          description: >-
            JSON Schema for the input. Optional; defaults to string when
            omitted.
          type: object
        instructions:
          type: string
        model:
          oneOf:
            - description: Model identifier (e.g. "openai/gpt-4o")
              type: string
            - properties:
                extra_headers:
                  description: Extra HTTP headers to send with requests to this model
                  type: object
                name:
                  description: Model identifier (e.g. "openai/gpt-4o")
                  type: string
                options:
                  description: >-
                    Per-model parameters (temperature, max_tokens,
                    reasoning_effort, etc.)
                  type: object
              required:
                - name
              type: object
            - description: Fallback chain — models tried in order on retriable errors
              items:
                oneOf:
                  - type: string
                  - properties:
                      extra_headers:
                        description: Extra HTTP headers to send with requests to this model
                        type: object
                      name:
                        description: Model identifier (e.g. "openai/gpt-4o")
                        type: string
                      options:
                        description: >-
                          Per-model parameters (temperature, max_tokens,
                          reasoning_effort, etc.)
                        type: object
                    required:
                      - name
                    type: object
              type: array
        name:
          type: string
        output_schema:
          description: >-
            JSON Schema for the output. Optional; defaults to string when
            omitted.
          type: object
        parent_span_id:
          type: string
        reasoning_effort:
          description: Reasoning effort for reasoning-capable models. One of "low"
          type: string
        reasoning_summary:
          description: Opt into thought summary streaming. "auto"
          type: string
        route:
          properties:
            prefer:
              type: string
          type: object
        stream:
          type: boolean
        tools:
          items:
            properties:
              description:
                type: string
              name:
                type: string
              parameters:
                type: object
              type:
                type: string
            required:
              - name
            type: object
          type: array
      required:
        - name
        - input
      type: object
    RunResponse:
      properties:
        data:
          description: Any value
        meta:
          properties:
            cost:
              type: number
            execution_ms:
              type: integer
            function_name:
              type: string
            generation_ms:
              type: integer
            guards:
              items:
                properties:
                  code:
                    type: string
                  findings:
                    items:
                      description: Any value
                    type: array
                  flagged:
                    type: boolean
                  phase:
                    type: string
                  rule_id:
                    type: string
                  rule_name:
                    type: string
                  scope_type:
                    type: string
                  status:
                    type: string
                  type:
                    type: string
                required:
                  - type
                  - flagged
                type: object
              type: array
            image_gen_calls:
              type: integer
            llm_calls:
              type: integer
            message:
              type: string
            model_warnings:
              items:
                type: string
              type: array
            models_used:
              items:
                type: string
              type: array
            pending_operations:
              items:
                properties:
                  id:
                    type: string
                  status_url:
                    type: string
                  type:
                    type: string
                required:
                  - id
                  - status_url
                  - type
                type: object
              type: array
            script_cached:
              type: boolean
            status:
              type: string
            tool_calls:
              items:
                type: object
              type: array
            trace_uuid:
              type: string
            tts_calls:
              type: integer
            usage:
              properties:
                cache_creation_1h_tokens:
                  type: integer
                cache_creation_tokens:
                  type: integer
                cache_read_tokens:
                  type: integer
                input_tokens:
                  type: integer
                output_tokens:
                  type: integer
                reasoning_tokens:
                  type: integer
              required:
                - input_tokens
                - output_tokens
              type: object
          required:
            - function_name
            - script_cached
            - execution_ms
            - llm_calls
            - tts_calls
            - image_gen_calls
          type: object
      required:
        - data
      type: object
    PendingResponse:
      properties:
        data:
          description: Any value
        meta:
          properties:
            execution_ms:
              type: integer
            function_name:
              type: string
            pending_operations:
              items:
                properties:
                  id:
                    type: string
                  status_url:
                    type: string
                  type:
                    type: string
                required:
                  - id
                  - status_url
                  - type
                type: object
              type: array
            status:
              enum:
                - pending
              type: string
          required:
            - function_name
            - status
            - execution_ms
            - pending_operations
          type: object
      required:
        - data
        - meta
      type: object
    ErrorResponse:
      properties:
        error:
          properties:
            code:
              type: string
            details:
              description: Any value
            message:
              type: string
          required:
            - code
            - message
          type: object
        meta:
          type: object
      required:
        - error
      type: object
  securitySchemes:
    BearerAuth:
      bearerFormat: API Key
      description: API key authentication. Pass your API key as a Bearer token.
      scheme: bearer
      type: http

````