Agent Gateway

The Agent Gateway is an AI-powered endpoint that accepts natural language queries about the directory and returns structured responses. It is designed for AI agent systems (e.g. procurement AI, chatbots, copilots) to discover suppliers, compare products, and answer sourcing questions.

POST

/agent-gateway

Send a natural language query and receive an AI-generated response with directory data.

agent.query

Base URL

https://rjpxllsycikfabazvkdh.supabase.co/functions/v1/agent-gateway

The Agent Gateway is a separate Edge Function from the main Directory API. Use the URL above, not the /v1/ REST API base URL.

Authentication

The Agent Gateway supports two authentication methods:

Method	Header	Requirements
API Key	`X-API-Key: bym_...`	Key must have `agent.query` permission scope
Supabase Auth	`Authorization: Bearer <token>`	User must have `admin` or `super_admin` role

Request Body

Field	Type	Default	Description
`query`	string	—	Required. Natural language query about the directory
`context_types`	string[]	`["businesses", "categories"]`	Data types to search: `businesses`, `categories`, `products`
`include_semantic`	boolean	`true`	Whether to use semantic (AI) search for context gathering
`limit`	integer	10	Max results to include in context (1-20)

How It Works

Context gathering: Searches the directory using semantic search (vector similarity) or keyword fallback to find relevant businesses, products, and categories
AI processing: Sends the gathered context + your query to the AI provider (supports multi-provider failover: OpenAI → Gemini → DeepSeek)
Structured response: The AI generates a response using ONLY the context data — never fabricates businesses or details
Response parsing: If the AI returns valid JSON, it's returned as structured type; otherwise as text type

Example Request

cURLbash

curl -X POST "https://rjpxllsycikfabazvkdh.supabase.co/functions/v1/agent-gateway" \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Find me verified furniture suppliers in Bali that can fulfill bulk orders",
    "context_types": ["businesses", "products"],
    "limit": 10
  }'

TypeScripttypescript

const response = await fetch('https://rjpxllsycikfabazvkdh.supabase.co/functions/v1/agent-gateway', {
  method: 'POST',
  headers: {
    'X-API-Key': API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    query: 'Find verified furniture suppliers in Bali for bulk orders',
    context_types: ['businesses', 'products'],
    limit: 10,
  }),
});

const data = await response.json();

if (data.response_type === 'structured') {
  // AI returned parsed JSON
  console.log(data.response.suppliers);
} else {
  // AI returned free text
  console.log(data.response);
}

Response

{
  "query": "Find verified furniture suppliers in Bali for bulk orders",
  "response": {
    "found": true,
    "suppliers": [
      {
        "id": "uuid-1",
        "name": "PT Furniture Jaya",
        "slug": "pt-furniture-jaya",
        "category": "Office Furniture",
        "region": "Bali",
        "verified": true,
        "can_fulfill_orders": true,
        "contact": { "phone": "+62812345678", "email": "info@furniturejaya.com" }
      }
    ],
    "summary": "Found 3 verified furniture suppliers in Bali capable of fulfilling bulk orders."
  },
  "response_type": "structured",
  "ai_provider": "openai",
  "context_sources": ["businesses", "products"]
}

Fallback: No AI Provider

If no AI providers are configured, the gateway returns raw search results instead:

{
  "query": "furniture suppliers bali",
  "ai_available": false,
  "raw_context": "## Relevant Businesses (5 found)\n[...]",
  "message": "No AI providers configured. Returning raw search results."
}

Error Responses

Status	Cause
401	Missing or invalid API key / auth token
403	API key lacks `agent.query` scope, or user is not admin
400	Missing or empty `query` field
500	AI provider error or internal failure

Integrations

MCP Server

Last updated on March 15, 2026