Hayride AI

Hayride AI API

The Hayride AI Server provides a dedicated API for AI-based interactions. This server is enabled by activating the ai feature during initialization:

hayride init --features.ai.enabled

Once enabled, the server exposes HTTP endpoints that allow interaction with AI agents using structured message payloads.

warning

The Hayride AI API is currently in alpha. Breaking changes may occur in upcoming releases. Please consult release notes and this documentation when integrating with this API.

Configuration

To use the AI server, your Hayride configuration file must define the ai feature with both a binary and HTTP address.

Hayride installs with default values, which can be customized as needed:

features:
  ai:
    bin: "hayride:ai-server@0.0.1"
    http:
      address: "http://localhost:8082"

tip

For detailed configuration options, see the Configuration Guide .

API Endpoints

Post /v1/generate

Submits a generation request to the AI agent. This endpoint accepts a list of structured messages and returns one or more generated responses. Depending on the agent, the result may be a single message or a sequence from an agent loop.

Request

Content-Type: application/json

Body:

{
  "data": {
    "messages": [
      {
        "role": "system",
        "content": [
          {
            "text": {
              "text": "You are a conversational agent, answer the user question with polite responses.",
              "content-type": "text/plain"
            }
          }
        ]
      },
      {
        "role": "user",
        "content": [
          {
            "text": {
              "text": "Hello, how are you?",
              "content-type": "text/plain"
            }
          }
        ]
      }
    ]
  }
}

Response

Returns a list of messages generated by the AI agent.

{
  "data": {
    "messages": [
      {
        "role": "assistant",
        "content": [
          {
            "text": {
              "text": "I'm just a tool calling agent, I don't have feelings or emotions. I'm here to help answer your questions and provide information to the best of my ability. How can I assist you today?",
              "content-type": "text"
            }
          }
        ]
      }
    ]
  }
}