Using the Generation and Assistant API 🤖

While the Randmar platform offers a comprehensive set of REST API endpoints for specific tasks, you can also programmatically interact with our AI models. This allows you to build sophisticated integrations that use the flexibility of conversational AI.

The API offers two primary modes: a powerful, tool-enabled Randmar Assistant for conversational tasks, and a direct-to-model endpoint for generating structured JSON data from a prompt.

Generation Endpoints ⚙️

You can interact with the AI models via a few different endpoints, depending on your goal. The body of your POST request for all endpoints is an array of objects representing the conversation history. Each object contains a role (e.g., "user" or "model") and an array of parts that make up the message.

API Update

The structure of the request and response bodies for the Generation endpoints has been simplified. This is a breaking change designed to remove external library dependencies from our API contract, making it more stable for developers.

A simple request body would look like this:

[
  {
    "role": "user",
    "parts": [
      { "text": "Show me my open orders" }
    ]
  }
]

The assistant is also capable of using tools, which involves functionCall and functionResponse parts. When the model needs to use a tool, it will respond with a functionCall part. Your application should execute the function and send back the result in a functionResponse part as part of the next request's history.

API Update: functionCall arguments are now strings 🛠️

To make tool integration more straightforward, the structure of the functionCall part has been updated. The args field is now a simple dictionary of string key-value pairs. This is a breaking change. Previously, arguments could be of different types (like numbers or booleans); now, all argument values must be sent and received as strings.

API Update: functionResponse structure change 🛠️

Similarly, the structure of the functionResponse part has been simplified. This is a breaking change for integrations that use the Assistant's tool-calling features. The response field, which was previously a complex JSON object, has been replaced by a simple content field that accepts a string. You are now responsible for serializing any JSON data into a string before sending it.

Here is an example of a full tool-use conversation. First, the model responds with a functionCall:

[
  {
    "role": "model",
    "parts": [
      {
        "functionCall": {
          "name": "get_order_status",
          "args": {
            "order_number": "OW01099999"
          }
        }
      }
    ]
  }
]

After executing the function, your next request to the API should include the history, plus the function's result in a functionResponse:

[
  {
    "role": "user",
    "parts": [ { "text": "What is the status of order OW01099999?" } ]
  },
  {
    "role": "model",
    "parts": [
      {
        "functionCall": {
          "name": "get_order_status",
          "args": { "order_number": "OW01099999" }
        }
      }
    ]
  },
  {
    "role": "user",
    "parts": [
      {
        "functionResponse": {
          "name": "get_order_status",
          "content": "{\"status\": \"Shipped\", \"tracking_number\": \"1Z9999W99999999999\"}"
        }
      }
    ]
  }
]

• For Conversational AI: To have a rich, back-and-forth conversation with the Randmar Assistant (the same one that powers the chat in the Partner Dashboard), use this endpoint. It is capable of using tools to perform actions on your behalf. Endpoint: POST /V4/Partner/{applicationId}/Generation/RandmarAssistant

• For Structured Data: If your goal is to get a structured JSON object back from a natural language prompt, use this endpoint. It provides a direct way to ask the model to format its response as JSON. Endpoint: POST /V4/Partner/{applicationId}/Generation/JSON

Authentication: For all endpoints, you must authenticate using a Bearer Token just like any other API request.

Example: From Conversation to Data 💬➡️📊

Imagine you want to get a list of your open orders.

Conversational Request (Randmar Assistant)

If you send a request to the /RandmarAssistant endpoint, you get a human-readable, conversational response. The assistant may use tools in the background to get this information.

Example Prompt: "Show me my open orders"

Response (text/plain):

Of course! You have two open orders right now: Order OW01099999 for Customer A, and Order OW01099998 for Customer B. Would you like to see more details on either of them?

This is great for a chat UI, but difficult for an application to parse reliably.

Structured Data Request (JSON)

Now, let's make the same request to the /JSON endpoint to get a machine-readable response.

Example Prompt: "Show me my open orders as a JSON object"

Response (application/json):

{
  "open_orders": [
    {
      "order_number": "OW01099999",
      "customer_po": "PO-123",
      "status": "Processing",
      "order_date": "2025-08-12"
    },
    {
      "order_number": "OW01099998",
      "customer_po": "PO-456",
      "status": "Processing",
      "order_date": "2025-08-11"
    }
  ]
}

This response is structured, predictable, and ready for your application to use, all from a simple, natural language prompt. You can use this for nearly any data request, from product information to sales reports.

What's Next?

This concludes our current guides on API and Integrations. You are now equipped to authenticate with the API, monitor its status, and leverage the Assistant for both conversational and structured data tasks. Happy coding! 🚀