Skip to main content
Internal reference — not the public API

This documents NearSync's internal action-dispatch surface, used by the apps themselves and by tenant automations. It is not the public API and carries no stability guarantee — actions may change or be removed without notice. For the supported, versioned public API see API Reference.

AI Endpoints

Endpoints for AI-powered chat completion, PRD generation, and data enrichment. NearSync routes AI requests through a multi-provider system with Google Gemini as the primary provider and OpenAI as a fallback.

All endpoints use POST to the hyper-worker base URL with the type field specifying the action.

POST https://<project>.supabase.co/functions/v1/hyper-worker

ai-chat​

Authenticated - Requires JWT.

Send a chat completion request to the AI router. Supports both streaming (Server-Sent Events) and non-streaming responses. The model name determines which provider handles the request.

Rate limit: 30 requests per 60 seconds

Request​

{
  "type": "ai-chat",
  "prompt": "Summarize this deal and suggest next steps",
  "model": "gemini-1.5-flash",
  "history": [
    {
      "role": "user",
      "content": "What's the status of the Acme deal?"
    },
    {
      "role": "assistant",
      "content": "The Acme deal is currently in the proposal stage..."
    }
  ],
  "systemInstruction": "You are a CRM assistant helping sales teams.",
  "stream": false
}
FieldTypeRequiredDescription
promptstringYesThe user's current message
modelstringNoModel identifier. Prefix determines provider: gemini-* routes to Google Gemini, gpt-* routes to OpenAI. Defaults to the organization's configured model
historyarrayNoConversation history as an array of {role, content} objects. Roles: user, assistant
systemInstructionstringNoSystem prompt that sets the AI's behavior and context
streambooleanNoIf true, returns a Server-Sent Events stream. Default: false

Provider Routing​

Model prefixProviderExamples
gemini-Google Geminigemini-1.5-flash, gemini-1.5-pro
gpt-OpenAIgpt-4o, gpt-4o-mini

Response (Non-Streaming)​

{
  "text": "The deal is in final negotiation stage with 95% probability of closing this quarter."
}

Response (Streaming)​

When stream: true, the endpoint returns a text/event-stream response with Server-Sent Events. Each event contains a chunk of the generated text:

data: {"text": "The deal "}
data: {"text": "is in final "}
data: {"text": "negotiation stage..."}
data: [DONE]

Consume the stream using the EventSource API or a streaming fetch reader:

const response = await fetch(HYPER_WORKER_URL, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify({
    type: 'ai-chat',
    prompt: 'Summarize this deal',
    stream: true
  })
})

const reader = response.body.getReader()
const decoder = new TextDecoder()

while (true) {
  const { done, value } = await reader.read()
  if (done) break
  const chunk = decoder.decode(value)
  // Parse SSE data lines
}

prd (AI-Generated PRD)​

Public - No authentication required.

Create a project with an AI-generated Product Requirements Document. If generatedPrd is omitted but rawData is provided, the endpoint calls Google Gemini to generate a structured PRD from the input.

Rate limit: 5 requests per 60 seconds

See CRM Endpoints - prd for the full request/response schema. The AI generation aspect works as follows:

AI Generation​

When rawData is provided without generatedPrd:

{
  "type": "prd",
  "clientName": "Jane Doe",
  "clientEmail": "client@example.com",
  "businessName": "Acme Corp",
  "rawData": {
    "problem": "Manual inventory tracking is time-consuming",
    "users": "Store managers and staff",
    "features": ["Real-time inventory", "Mobile app", "Reports"]
  }
}

The endpoint sends the rawData to Google Gemini with a structured prompt to generate a PRD covering problem statement, target users, feature requirements, and technical considerations. The generated PRD is stored with the project record.

enrich-project​

Authenticated - Requires JWT.

Use AI to research and enrich a deal record with company intelligence. See CRM Endpoints - enrich-project for the full schema.

The enrichment calls Google Gemini with the company name and extracts:

  • Industry classification
  • Employee count estimate
  • Website URL
  • Physical address
  • Company logo URL
  • Business summary

enrich-organization​

Authenticated - Requires JWT.

Use AI to research and enrich a CRM company record. See CRM Endpoints - enrich-organization for the full schema.

Similar to enrich-project but enriches the company name and website to extract industry, founding year, description, and employee range.

Workflow AI Node​

The workflow engine supports a pippin node type that sends data through Google Gemini for in-workflow AI analysis. This is not a standalone endpoint but a node within the execute-workflow system. The AI analysis result feeds into subsequent workflow nodes for conditional branching or action execution.

Error Handling​

AI endpoints return standard error responses. Common failure modes:

ScenarioStatusError
Rate limit exceeded429"Rate limited. Try again in N seconds"
Provider API error500"Failed to generate response: <provider error>"
Invalid model name400"Unsupported model: <model>"
Empty prompt400"Missing required field: prompt"

When the primary provider (Gemini) is unavailable, the system falls back to OpenAI automatically for ai-chat requests. For enrichment and PRD generation, Gemini is the only provider - failures return a 500 error.

  • CRM Endpoints - AI enrichment endpoints are documented alongside CRM operations
  • Rate Limits - AI chat has a higher rate limit (30/min) than most endpoints