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

# Invoke

Invokes an endpoint to execute a specific operation using the Rapida API.

<Info>
  For full setup and authentication options, see the Installation guide: [Installation guide](/api-reference/installation) and [Authentication](/api-reference/authentication).
</Info>

## Parameters

<ParamField body="connectionConfig" type="ConnectionConfig" required>
  Configuration for the client connection.
</ParamField>

<ParamField body="request" type="InvokeRequest" required>
  <Expandable>
    <ParamField body="endpoint" type="EndpointDefinition" required>
      <Expandable>
        <ParamField body="endpointId" type="number" required>
          Unique identifier of the endpoint to invoke.
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField body="args" type="Map<string, google_protobuf_any_pb.Any>">
      Arguments passed to the endpoint as a key-value map.
    </ParamField>

    <ParamField body="options" type="Map<string, google_protobuf_any_pb.Any>">
      Request options for runtime behavior and configuration.
    </ParamField>

    <ParamField body="metadata" type="Map<string, google_protobuf_any_pb.Any>">
      Metadata associated with the request for tracking and analytics.
    </ParamField>
  </Expandable>
</ParamField>

### Usage

<CodeGroup>
  ```python Python theme={null}
  from rapida import (
      ConnectionConfig,
      EndpointDefinition,
      InvokeRequest,
      invoke,
      string_to_any,
  )
  from pprint import pprint
  connection_config = ConnectionConfig.default_connection_config(
      ConnectionConfig.with_sdk("{your-rapida-api-key}")
  )

  argument_value = string_to_any("Hello how are you doing")
  metadata_value = string_to_any("metadata_to_track")
  option_value = string_to_any("4567898656789")

  response = invoke(
      client_cfg=connection_config,
      request=InvokeRequest(
          endpoint=EndpointDefinition(endpointId=2223006263292198912),
          args={"can": argument_value},
          metadata={"test": metadata_value},
          options={"opts1": option_value},
      ),
  )
  pprint(response)
  ```

  ```go Go theme={null}
  package main

  import (
  	"context"
  	"fmt"

  	clients "github.com/rapidaai/rapida-go/rapida/clients"
  	rapida_proto "github.com/rapidaai/rapida-go/rapida/clients/protos"
  	connections "github.com/rapidaai/rapida-go/rapida/connections"
  	"github.com/rapidaai/rapida-go/rapida/utils"
  	"google.golang.org/protobuf/types/known/anypb"
  )

  func main() {
  	// for more authentication check https://doc.rapida.ai/api-reference/authentication
  	connectionConfig := connections.
  		DefaultconnectionConfig(connections.WithSDK("RAPIDA_PROJECT_CREDENTIAL"))
  	argumentValue, _ := utils.StringToAny("Hello how are you doing")
  	metadataValue, _ := utils.StringToAny("metadata_to_track")
  	optionValue, _ := utils.Int64ToAny(4567898656789)
  	response, _ := clients.Invoke(context.Background(), connectionConfig, &rapida_proto.InvokeRequest{
  		Endpoint: &rapida_proto.EndpointDefinition{
  			EndpointId: RAPIDA_ENDPOINT_ID,
  		},
  		Args: map[string]*anypb.Any{
  			"can": argumentValue,
  		},
  		Metadata: map[string]*anypb.Any{
  			"test": metadataValue,
  		},
  		Options: map[string]*anypb.Any{
  			"opts1": optionValue,
  		},
  	})

    for _, content:= range response.GetMetrics() {
      fmt.Println(string(content.Name), string(content.Value))
    }

    for _, content:= range response.GetData() {
      fmt.Println(string(content.GetContent()))
    }

  }
  ```

  ```typescript NodeJs  theme={null}
  import {
    Invoke,
    ConnectionConfig,
    GetEndpoint,
    InvokeRequest,
    EndpointDefinition,
    StringToAny,
    ToContentText
  } from "@rapidaai/nodejs";

  (async () => {
    const connectionCfg = ConnectionConfig.DefaultConnectionConfig(
      ConnectionConfig.WithSDK({
        ApiKey: process.env.RAPIDA_PROJECT_CREDENTIAL,
      })
    );
    invokeEndpoint(connectionCfg)
  })();


  async function invokeEndpoint(connectionCfg) {
    const request = new InvokeRequest();
    let endpointDef = new EndpointDefinition();
    endpointDef.setEndpointid(RAPIDA_ENDPOINT_ID);
    endpointDef.setVersion("latest");
    request.setEndpoint(endpointDef);
    request.getArgsMap().set("can", StringToAny("Prompt_ARGUMENT"));
    request.getArgsMap().set("can", StringToAny("Prompt_ARGUMENT_2"));

    // metadata
    request.getMetadataMap().set("track", StringToAny("metadata_to_track"));

    // options
    request.getOptionsMap().set("model_options", StringToAny("x"));
    const response = await Invoke(connectionCfg, request);
    if (response.getError()) {
      console.error(
        "Error invoking endpoint:",
        response.getError()?.getHumanmessage()
      );
    } else {
      console.log("Endpoint invoked successfully:", ToContentText(response.getDataList()));
      response.getMetricsList().forEach(x => console.log(x.getName(), x.getValue()))
    }
  }
  ```
</CodeGroup>

### Response

<ParamField body="code" type="int">
  Numeric status code for the operation.
</ParamField>

<ParamField body="success" type="boolean">
  Indicates whether the operation was successful.
</ParamField>

<ParamField body="error" type="Error">
  <Expandable>
    <ResponseField name="errorCode" type="string (uint64)">
      Stable, machine-readable numeric code for the error.
    </ResponseField>

    <ResponseField name="errorMessage" type="string">
      Developer-oriented error message for debugging.
    </ResponseField>

    <ResponseField name="humanMessage" type="string">
      End-user-friendly error message.
    </ResponseField>
  </Expandable>
</ParamField>

<ParamField body="data" type="array" description="Array of Content, representing the returned results.">
  <Expandable>
    <ParamField body="name" type="string">
      Name of the content.
    </ParamField>

    <ParamField body="contentType" type="string">
      Type of the content (e.g., audio, image, video, text).
    </ParamField>

    <ParamField body="contentFormat" type="string">
      Format of the content (e.g., raw string, URL).
    </ParamField>

    <ParamField body="content" type="bytes">
      Raw content data.
    </ParamField>

    <ParamField body="meta" type="object">
      Metadata of the content.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="requestId" type="uint64">
  Unique ID for tracking the request.
</ParamField>

<ParamField body="timeTaken" type="uint64">
  Duration of the operation in milliseconds.
</ParamField>

<ParamField body="metrics" type="array" description="Performance metrics captured during the request.">
  <Expandable>
    <ParamField body="name" type="string">
      Name of the metric.
    </ParamField>

    <ParamField body="value" type="string">
      Value of the metric.
    </ParamField>

    <ParamField body="description" type="string">
      Description of the metric.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="meta" type="object" description="Structured metadata related to the response." />