API Integration

Build custom documentation search into your apps, bots, and workflows with the ULPI REST API

Build Documentation Search Into Your Applications

Your team needs documentation search in places ULPI doesn’t reach:

• Internal documentation portals
• Slack bots for instant doc lookups
• IDE extensions
• CLI tools
• Admin dashboards
• Custom AI agents

The ULPI REST API lets you integrate semantic documentation search anywhere.

This guide shows you:

• 🔌 How to authenticate and make your first API call (2 minutes)
• 💡 Real-world integration examples (Slack bots, portals, CLI tools)
• 🛠️ Production-ready code in JavaScript, Python, PHP, Go
• ⚡ Best practices for caching, rate limits, and error handling
• 📊 Performance optimization strategies

Just want to use ULPI with Claude/Cursor? See Getting Started for MCP setup instead.

Building something custom? This guide is for you.

---

Why Use the API?

The MCP server is great for AI assistants, but the API unlocks custom integrations:

Custom Search UIs

Build internal documentation portals:

• Company-branded search interface
• Advanced filtering and faceting
• Usage analytics and tracking
• Integration with SSO/auth

Example: Acme Corp’s internal dev portal with ULPI search

Slack/Discord Bots

Instant doc lookups in chat:

• /docs deploy to production → Get deployment guide
• No context switching
• Share results with team
• Track common questions

Example: Engineering Slack bot with 500+ daily searches

CLI Tools

Terminal-based documentation search:

• docs auth → Find auth docs
• Integrate with shell scripts
• CI/CD pipeline helpers
• Developer productivity boost

Example: company-docs CLI tool for all repos

Custom AI Agents

Build specialized AI assistants:

• Customer support chatbots
• Onboarding assistants
• Technical troubleshooting bots
• Integration with your AI stack

Example: Support bot that searches internal docs first

Plus: Dashboards, IDE plugins, mobile apps, workflow automation, and more.

---

Quick Start: Your First API Call

Get up and running in 2 minutes:

1. Get Your API Key

   Generate an API key:

   1. Go to app.ulpi.io/api-keys
   2. Click Create API Key
   3. Name: “API Integration Test”
   4. Environment: live (production)
   5. Copy the key (starts with ulpi_live_sk_...)

   Save your API key immediately! It’s only shown once.

   Store in password manager or environment variable.

2. Make Your First Request

   Test with cURL:

   curl -X POST https://api.ulpi.io/api/v1/documentation/search \
     -H "Authorization: Bearer ulpi_live_YOUR_KEY_HERE" \
     -H "Content-Type: application/json" \
     -d '{
       "query": "How do I deploy to production?",
       "limit": 3
     }'
   

   Replace ulpi_live_YOUR_KEY_HERE with your actual API key.

3. View Results

   You’ll get JSON response:

   {
     "results": [
       {
         "content": "To deploy to production:\n\n1. Run tests...",
         "file": "docs/deployment.md",
         "repository": "backend-api",
         "branch": "main",
         "url": "https://github.com/org/repo/blob/main/docs/deployment.md#L42",
         "score": 0.94,
         "last_updated": "2025-01-10T14:23:00Z"
       }
     ],
     "meta": {
       "total": 12,
       "query_time_ms": 45,
       "cached": false
     }
   }
   

   Success! You just searched your documentation via API.

4. Integrate Into Your App

   Choose your language:

   • JavaScript/TypeScript
   • Python
   • PHP
   • Go

   Or: Use the REST API directly

Total time: 2 minutes from API key to first results

---

Real-World Integration Examples

See how teams use the ULPI API:

🤖 Slack Bot for Documentation Lookup

Use case: Engineers ask /docs <question> in Slack, bot returns relevant docs

Benefits:

• No context switching (stay in Slack)
• Share results with team instantly
• Track most-asked questions
• Reduce Slack interruptions (“Where’s the deploy doc?”)

Implementation:

Bolt.js (JavaScript)

// slack-bot.js
const { App } = require('@slack/bolt');

const app = new App({
  token: process.env.SLACK_BOT_TOKEN,
  signingSecret: process.env.SLACK_SIGNING_SECRET
});

// /docs command
app.command('/docs', async ({ command, ack, respond }) => {
  await ack();

  // Search ULPI
  const results = await fetch('https://api.ulpi.io/api/v1/documentation/search', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.ULPI_API_KEY}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      query: command.text,
      limit: 3
    })
  }).then(r => r.json());

  // Format for Slack
  await respond({
    text: `Found ${results.meta.total} results for "${command.text}":`,
    blocks: results.results.map(r => ({
      type: 'section',
      text: {
        type: 'mrkdwn',
        text: `*${r.file}* (${r.repository})\n${r.content.substring(0, 300)}...\n<${r.url}|View on GitHub>`
      }
    }))
  });
});

app.start(3000);

Usage in Slack:

/docs how to deploy to production
/docs authentication with JWT
/docs troubleshoot 500 errors

Python (slack_sdk)

# slack_bot.py
from slack_bolt import App
from slack_bolt.adapter.socket_mode import SocketModeHandler
import requests
import os

app = App(token=os.environ["SLACK_BOT_TOKEN"])

@app.command("/docs")
def handle_docs_command(ack, command, respond):
    ack()

    query = command['text']

    # Search ULPI
    response = requests.post(
        'https://api.ulpi.io/api/v1/documentation/search',
        headers={
            'Authorization': f'Bearer {os.environ["ULPI_API_KEY"]}',
            'Content-Type': 'application/json'
        },
        json={'query': query, 'limit': 3}
    )

    results = response.json()

    # Format response
    blocks = [{
        'type': 'section',
        'text': {
            'type': 'mrkdwn',
            'text': f"*{r['file']}* ({r['repository']})\n{r['content'][:300]}...\n<{r['url']}|View on GitHub>"
        }
    } for r in results['results']]

    respond(
        text=f"Found {results['meta']['total']} results for \"{query}\":",
        blocks=blocks
    )

if __name__ == "__main__":
    handler = SocketModeHandler(app, os.environ["SLACK_APP_TOKEN"])
    handler.start()

Deployment:

• Deploy to Heroku, AWS Lambda, or any Node/Python host
• Set environment variables: SLACK_BOT_TOKEN, ULPI_API_KEY
• Invite bot to Slack channels

Result: Instant documentation lookup without leaving Slack

🌐 Internal Documentation Portal

Use case: Company-branded docs website with ULPI search

Benefits:

• Centralized documentation access
• Advanced search with filters
• Usage analytics (what’s searched most)
• SSO integration

Implementation (Next.js):

API Route

// pages/api/search.ts
import type { NextApiRequest, NextApiResponse } from 'next';

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  if (req.method !== 'POST') {
    return res.status(405).json({ error: 'Method not allowed' });
  }

  const { query, repository, limit = 10 } = req.body;

  // Call ULPI API (server-side keeps API key secure)
  const response = await fetch(
    'https://api.ulpi.io/api/v1/documentation/search',
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.ULPI_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ query, repository, limit })
    }
  );

  const data = await response.json();

  // Log for analytics
  await logSearch(query, data.meta.total);

  res.status(200).json(data);
}

Search Component

// components/SearchBar.tsx
import { useState } from 'react';

export default function SearchBar() {
  const [query, setQuery] = useState('');
  const [results, setResults] = useState([]);
  const [loading, setLoading] = useState(false);

  const handleSearch = async (q: string) => {
    setLoading(true);

    const res = await fetch('/api/search', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ query: q })
    });

    const data = await res.json();
    setResults(data.results);
    setLoading(false);
  };

  return (
    <div className="search-container">
      <input
        type="text"
        placeholder="Search documentation..."
        value={query}
        onChange={(e) => {
          setQuery(e.target.value);
          if (e.target.value.length > 2) {
            handleSearch(e.target.value);
          }
        }}
      />

      {loading && <Spinner />}

      <div className="results">
        {results.map((result) => (
          <SearchResult key={result.url} result={result} />
        ))}
      </div>
    </div>
  );
}

Result Display

// components/SearchResult.tsx
interface SearchResultProps {
  result: {
    file: string;
    repository: string;
    content: string;
    url: string;
    score: number;
    last_updated: string;
  };
}

export default function SearchResult({ result }: SearchResultProps) {
  return (
    <div className="result-card">
      <div className="result-header">
        <h3>{result.file}</h3>
        <span className="repo-badge">{result.repository}</span>
        <span className="score">
          {Math.round(result.score * 100)}% match
        </span>
      </div>

      <p className="result-content">
        {result.content.substring(0, 300)}...
      </p>

      <div className="result-footer">
        <a href={result.url} target="_blank" rel="noopener">
          View on GitHub →
        </a>
        <span className="last-updated">
          Updated {new Date(result.last_updated).toLocaleDateString()}
        </span>
      </div>
    </div>
  );
}

Features to add:

• Repository filter dropdown
• Branch selector
• Search history
• Bookmarks
• Analytics dashboard

Example: docs.acmecorp.com - internal portal with 1,000+ daily searches

🖥️ CLI Tool for Terminal Search

Use case: Search docs from terminal without opening browser

Benefits:

• Stay in terminal workflow
• Script-friendly (use in automation)
• Fast lookups during coding
• Pipe output to other commands

Implementation (Python Click):

# company_docs.py
import click
import requests
import os
from rich.console import Console
from rich.markdown import Markdown

console = Console()
ULPI_API_KEY = os.getenv('ULPI_API_KEY')

def search_docs(query, repo=None, limit=5):
    """Search ULPI documentation."""
    response = requests.post(
        'https://api.ulpi.io/api/v1/documentation/search',
        headers={
            'Authorization': f'Bearer {ULPI_API_KEY}',
            'Content-Type': 'application/json'
        },
        json={
            'query': query,
            'repository': repo,
            'limit': limit
        }
    )
    response.raise_for_status()
    return response.json()

@click.group()
def cli():
    """Company documentation search CLI."""
    pass

@cli.command()
@click.argument('query')
@click.option('--repo', '-r', help='Filter by repository')
@click.option('--limit', '-n', default=5, help='Number of results')
@click.option('--open', '-o', is_flag=True, help='Open first result in browser')
def search(query, repo, limit, open):
    """Search documentation."""
    console.print(f"[bold]Searching for:[/bold] {query}\n")

    results = search_docs(query, repo, limit)

    console.print(f"[green]Found {results['meta']['total']} results[/green] "
                 f"(showing {len(results['results'])})\n")

    for i, result in enumerate(results['results'], 1):
        console.print(f"[bold cyan]{i}. {result['file']}[/bold cyan] "
                     f"({result['repository']})")
        console.print(f"   {result['content'][:200]}...")
        console.print(f"   [dim]{result['url']}[/dim]\n")

    if open and results['results']:
        import webbrowser
        webbrowser.open(results['results'][0]['url'])

@cli.command()
def interactive():
    """Interactive search mode."""
    while True:
        query = click.prompt('\nSearch (or "q" to quit)')
        if query.lower() == 'q':
            break

        results = search_docs(query, limit=3)

        for i, result in enumerate(results['results'], 1):
            console.print(f"\n{i}. [bold]{result['file']}[/bold]")
            console.print(Markdown(result['content'][:300]))

if __name__ == '__main__':
    cli()

Installation:

# Install as global command
pip install -e .

# Or create alias
alias docs="python /path/to/company_docs.py"

Usage:

# Search
docs search "deploy to production"

# Filter by repo
docs search "authentication" --repo backend-api

# Open first result in browser
docs search "troubleshoot" --open

# Interactive mode
docs interactive

Result: Documentation lookup without leaving terminal

📊 Dashboard Widget

Use case: Quick doc access in admin dashboard

Benefits:

• Context-aware quick links
• Common runbooks one click away
• New hire onboarding helper
• Embedded in existing tools

Implementation (React):

// DocsWidget.tsx
import { useState, useEffect } from 'react';

const quickTopics = [
  { label: 'Deploy to Prod', query: 'deployment production' },
  { label: 'API Auth', query: 'API authentication' },
  { label: 'Troubleshoot 500s', query: 'troubleshoot 500 errors' },
  { label: 'Local Setup', query: 'local development setup' }
];

export function DocsWidget() {
  const [selectedDoc, setSelectedDoc] = useState(null);

  const quickSearch = async (query) => {
    const res = await fetch('/api/search', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ query, limit: 1 })
    });

    const data = await res.json();
    setSelectedDoc(data.results[0]);
  };

  return (
    <div className="docs-widget">
      <h3>Quick Docs</h3>

      <div className="quick-links">
        {quickTopics.map(topic => (
          <button
            key={topic.query}
            onClick={() => quickSearch(topic.query)}
            className="quick-link-btn"
          >
            {topic.label}
          </button>
        ))}
      </div>

      {selectedDoc && (
        <div className="doc-preview">
          <h4>{selectedDoc.file}</h4>
          <p>{selectedDoc.content.substring(0, 200)}...</p>
          <a href={selectedDoc.url} target="_blank">
            View full doc →
          </a>
        </div>
      )}
    </div>
  );
}

Use in dashboard:

• Employee onboarding page
• Developer tools section
• Help/support sidebar
• Context-sensitive (show relevant docs per page)

🤖 Custom AI Assistant

Use case: Customer support chatbot that searches internal docs

Benefits:

• Accurate answers from YOUR documentation
• Reduces support ticket volume
• 24/7 availability
• Cites sources (links to docs)

Implementation (LangChain + OpenAI):

# support_bot.py
from langchain.chat_models import ChatOpenAI
from langchain.agents import Tool, initialize_agent
import requests
import os

def search_documentation(query: str) -> str:
    """Search company documentation."""
    response = requests.post(
        'https://api.ulpi.io/api/v1/documentation/search',
        headers={
            'Authorization': f'Bearer {os.environ["ULPI_API_KEY"]}',
            'Content-Type': 'application/json'
        },
        json={'query': query, 'limit': 3}
    )

    results = response.json()['results']

    # Format for LLM
    docs_text = "\n\n".join([
        f"From {r['file']}:\n{r['content']}\nSource: {r['url']}"
        for r in results
    ])

    return docs_text

# Create tool for LangChain
doc_search_tool = Tool(
    name="SearchDocumentation",
    func=search_documentation,
    description="Search company documentation for technical information, "
                "deployment guides, troubleshooting steps, etc."
)

# Initialize agent
llm = ChatOpenAI(temperature=0, model="gpt-4")
agent = initialize_agent(
    tools=[doc_search_tool],
    llm=llm,
    agent="zero-shot-react-description",
    verbose=True
)

# Use agent
response = agent.run(
    "How do I deploy our backend API to production?"
)

print(response)
# Agent automatically calls search_documentation tool,
# gets relevant docs, and formulates answer with citations

Deploy as:

• Slack bot
• Website chat widget
• Support ticket assistant
• Email autoresponder

---

API Reference

Complete API endpoint documentation:

Authentication

All requests require API key in Authorization header:

Authorization: Bearer ulpi_live_sk_abc123...

API key formats:

• ulpi_live_sk_... - Production environment
• ulpi_test_sk_... - Testing environment

Generate keys: app.ulpi.io/api-keys

---

POST /api/v1/documentation/search

Search across indexed documentation

Base URL: https://api.ulpi.io/api/v1/documentation/search

Request Body:

{
  "query": "How do I deploy to production?",
  "repository": "backend-api",
  "branch": "main",
  "limit": 10
}

Parameters:

Parameter	Type	Required	Description	Default
query	string	✅ Yes	Natural language search query	-
repository	string	❌ No	Filter to specific repository	All repos
branch	string	❌ No	Search specific branch	Default branch
limit	integer	❌ No	Max results (1-20)	10

Query Guidelines:

• Max length: 500 characters
• Natural language: “How do I…” works better than keywords
• Be specific: “deploy to AWS production” better than “deploy”

Response:

{
  "results": [
    {
      "content": "Full text excerpt from documentation...",
      "file": "docs/deployment.md",
      "repository": "backend-api",
      "branch": "main",
      "url": "https://github.com/org/repo/blob/main/docs/deployment.md#L42",
      "score": 0.94,
      "last_updated": "2025-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "total": 12,
    "query_time_ms": 45,
    "cached": false
  }
}

Response Fields:

Field	Type	Description
results[]	array	Array of search results (sorted by relevance)
results[].content	string	Documentation excerpt (most relevant section)
results[].file	string	File path relative to repository root
results[].repository	string	Repository name
results[].branch	string	Git branch
results[].url	string	Direct link to file on GitHub/GitLab
results[].score	float	Relevance score (0.0-1.0, higher = better match)
results[].last_updated	string	ISO 8601 timestamp of last file update
meta.total	integer	Total results found (may be more than returned)
meta.query_time_ms	integer	Query execution time in milliseconds
meta.cached	boolean	Whether results were served from cache

---

Code Examples by Language

JavaScript / TypeScript

Node.js implementation:

// ulpi-client.ts
interface SearchOptions {
  repository?: string;
  branch?: string;
  limit?: number;
}

interface SearchResult {
  content: string;
  file: string;
  repository: string;
  branch: string;
  url: string;
  score: number;
  last_updated: string;
}

interface SearchResponse {
  results: SearchResult[];
  meta: {
    total: number;
    query_time_ms: number;
    cached: boolean;
  };
}

class ULPIClient {
  private apiKey: string;
  private baseUrl = 'https://api.ulpi.io/api/v1';

  constructor(apiKey: string) {
    this.apiKey = apiKey;
  }

  async searchDocumentation(
    query: string,
    options: SearchOptions = {}
  ): Promise<SearchResponse> {
    const response = await fetch(`${this.baseUrl}/documentation/search`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        query,
        repository: options.repository,
        branch: options.branch,
        limit: options.limit || 10,
      }),
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(`ULPI API error: ${error.message}`);
    }

    return response.json();
  }
}

// Usage
const ulpi = new ULPIClient(process.env.ULPI_API_KEY!);

const results = await ulpi.searchDocumentation(
  'How to deploy to production?',
  { repository: 'backend-api', limit: 5 }
);

results.results.forEach(result => {
  console.log(`${result.file}: ${result.content.substring(0, 100)}...`);
  console.log(`Score: ${result.score}, URL: ${result.url}\n`);
});

Python

Python implementation with requests:

# ulpi_client.py
import requests
from typing import Optional, List, Dict
import os

class ULPIClient:
    """Client for ULPI Documentation API."""

    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = 'https://api.ulpi.io/api/v1'

    def search_documentation(
        self,
        query: str,
        repository: Optional[str] = None,
        branch: Optional[str] = None,
        limit: int = 10
    ) -> Dict:
        """
        Search documentation across repositories.

        Args:
            query: Natural language search query
            repository: Optional repository filter
            branch: Optional branch filter
            limit: Max results (1-20)

        Returns:
            Dict with 'results' and 'meta' keys

        Raises:
            requests.HTTPError: If API request fails
        """
        response = requests.post(
            f'{self.base_url}/documentation/search',
            headers={
                'Authorization': f'Bearer {self.api_key}',
                'Content-Type': 'application/json'
            },
            json={
                'query': query,
                'repository': repository,
                'branch': branch,
                'limit': limit
            }
        )

        response.raise_for_status()
        return response.json()

# Usage
ulpi = ULPIClient(os.getenv('ULPI_API_KEY'))

results = ulpi.search_documentation(
    'How to deploy to production?',
    repository='backend-api',
    limit=5
)

for result in results['results']:
    print(f"{result['file']} (score: {result['score']:.2f})")
    print(f"{result['content'][:150]}...")
    print(f"{result['url']}\n")

print(f"Found {results['meta']['total']} results in {results['meta']['query_time_ms']}ms")

PHP

PHP implementation with Laravel HTTP:

<?php
// app/Services/UlpiClient.php

namespace App\Services;

use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\Cache;

class UlpiClient
{
    private string $apiKey;
    private string $baseUrl = 'https://api.ulpi.io/api/v1';

    public function __construct(string $apiKey)
    {
        $this->apiKey = $apiKey;
    }

    /**
     * Search documentation
     */
    public function searchDocumentation(
        string $query,
        ?string $repository = null,
        ?string $branch = null,
        int $limit = 10
    ): array {
        // Cache key
        $cacheKey = "ulpi:search:" . md5(json_encode([
            'query' => $query,
            'repository' => $repository,
            'branch' => $branch,
            'limit' => $limit
        ]));

        // Check cache (5 minutes)
        return Cache::remember($cacheKey, 300, function () use (
            $query, $repository, $branch, $limit
        ) {
            $response = Http::withHeaders([
                'Authorization' => "Bearer {$this->apiKey}",
            ])->post("{$this->baseUrl}/documentation/search", [
                'query' => $query,
                'repository' => $repository,
                'branch' => $branch,
                'limit' => $limit,
            ]);

            if ($response->failed()) {
                throw new \Exception(
                    "ULPI API error: " . $response->json('message')
                );
            }

            return $response->json();
        });
    }

    /**
     * Get first result for quick lookups
     */
    public function quickSearch(string $query): ?array
    {
        $results = $this->searchDocumentation($query, limit: 1);
        return $results['results'][0] ?? null;
    }
}

// Usage (in controller or service)
$ulpi = new UlpiClient(config('services.ulpi.api_key'));

$results = $ulpi->searchDocumentation(
    'How to deploy to production?',
    repository: 'backend-api',
    limit: 5
);

foreach ($results['results'] as $result) {
    echo "{$result['file']}: {$result['content']}\n";
    echo "{$result['url']}\n\n";
}

Go

Go implementation:

// ulpi/client.go
package ulpi

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "time"
)

type Client struct {
    APIKey  string
    BaseURL string
    client  *http.Client
}

type SearchOptions struct {
    Repository string `json:"repository,omitempty"`
    Branch     string `json:"branch,omitempty"`
    Limit      int    `json:"limit,omitempty"`
}

type SearchResult struct {
    Content     string    `json:"content"`
    File        string    `json:"file"`
    Repository  string    `json:"repository"`
    Branch      string    `json:"branch"`
    URL         string    `json:"url"`
    Score       float64   `json:"score"`
    LastUpdated time.Time `json:"last_updated"`
}

type SearchResponse struct {
    Results []SearchResult `json:"results"`
    Meta    struct {
        Total       int  `json:"total"`
        QueryTimeMs int  `json:"query_time_ms"`
        Cached      bool `json:"cached"`
    } `json:"meta"`
}

func NewClient(apiKey string) *Client {
    return &Client{
        APIKey:  apiKey,
        BaseURL: "https://api.ulpi.io/api/v1",
        client:  &http.Client{Timeout: 30 * time.Second},
    }
}

func (c *Client) SearchDocumentation(
    query string,
    opts *SearchOptions,
) (*SearchResponse, error) {
    if opts == nil {
        opts = &SearchOptions{Limit: 10}
    }

    payload := map[string]interface{}{
        "query":      query,
        "repository": opts.Repository,
        "branch":     opts.Branch,
        "limit":      opts.Limit,
    }

    jsonData, err := json.Marshal(payload)
    if err != nil {
        return nil, err
    }

    req, err := http.NewRequest(
        "POST",
        fmt.Sprintf("%s/documentation/search", c.BaseURL),
        bytes.NewBuffer(jsonData),
    )
    if err != nil {
        return nil, err
    }

    req.Header.Set("Authorization", fmt.Sprintf("Bearer %s", c.APIKey))
    req.Header.Set("Content-Type", "application/json")

    resp, err := c.client.Do(req)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    if resp.StatusCode != http.StatusOK {
        return nil, fmt.Errorf("API error: %s", resp.Status)
    }

    var searchResp SearchResponse
    if err := json.NewDecoder(resp.Body).Decode(&searchResp); err != nil {
        return nil, err
    }

    return &searchResp, nil
}

// Usage
package main

import (
    "fmt"
    "log"
    "os"
)

func main() {
    client := ulpi.NewClient(os.Getenv("ULPI_API_KEY"))

    results, err := client.SearchDocumentation(
        "How to deploy to production?",
        &ulpi.SearchOptions{
            Repository: "backend-api",
            Limit:      5,
        },
    )
    if err != nil {
        log.Fatal(err)
    }

    for _, result := range results.Results {
        fmt.Printf("%s (score: %.2f)\n", result.File, result.Score)
        fmt.Printf("%s\n", result.Content[:150])
        fmt.Printf("%s\n\n", result.URL)
    }

    fmt.Printf("Found %d results in %dms\n",
        results.Meta.Total,
        results.Meta.QueryTimeMs)
}

---

Rate Limits & Quotas

API limits by plan:

Plan	Requests/Min	Requests/Hour	Requests/Day	Burst
Starter	60	1,000	10,000	100
Professional	120	5,000	50,000	200
Enterprise	300	15,000	Unlimited	500

Rate limit headers (included in every response):

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640000000

429 Too Many Requests response:

{
  "error": "Rate limit exceeded",
  "message": "You have exceeded your rate limit of 60 requests per minute",
  "retry_after": 30
}

Best practices:

• Implement exponential backoff
• Cache results (5-15 minutes)
• Monitor X-RateLimit-Remaining
• Use batch queries when possible

---

Error Handling

HTTP status codes:

400 Bad Request

Cause: Invalid request parameters

{
  "error": "Invalid request",
  "message": "Query parameter is required",
  "field": "query"
}

Common issues:

• Missing query parameter
• limit out of range (1-20)
• query too long (>500 chars)

Fix: Validate parameters before sending

401 Unauthorized

Cause: Invalid or missing API key

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

Common issues:

• API key not in Authorization header
• Wrong key format
• Expired or revoked key

Fix: Verify API key and header format

403 Forbidden

Cause: API key lacks access to resource

{
  "error": "Forbidden",
  "message": "API key does not have access to repository 'backend-api'"
}

Fix: Check API key scopes or connect repository

404 Not Found

Cause: Resource doesn’t exist

{
  "error": "Not found",
  "message": "Repository 'backend-api' not found"
}

Fix: Verify repository name or connect repository

429 Too Many Requests

Cause: Rate limit exceeded

{
  "error": "Rate limit exceeded",
  "retry_after": 30
}

Fix: Implement backoff, cache results, or upgrade plan

500 Internal Server Error

Cause: Server-side issue

{
  "error": "Internal server error",
  "message": "Search service temporarily unavailable"
}

Fix: Retry with exponential backoff. Contact support if persistent.

Robust error handling:

async function searchWithRetry(
  query: string,
  maxRetries = 3
): Promise<SearchResponse> {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await ulpi.searchDocumentation(query);
    } catch (error) {
      // Don't retry client errors (4xx)
      if (error.status >= 400 && error.status < 500) {
        throw error;
      }

      // Last attempt - throw error
      if (attempt === maxRetries) {
        throw error;
      }

      // Exponential backoff: 1s, 2s, 4s
      const delay = Math.pow(2, attempt - 1) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

---

Best Practices

🗄️ Cache Results Aggressively

Cache search results to reduce API calls:

// Simple in-memory cache with TTL
class SearchCache {
  private cache = new Map<string, { data: any; expires: number }>();

  set(key: string, data: any, ttl = 300000) { // 5 min default
    this.cache.set(key, {
      data,
      expires: Date.now() + ttl
    });
  }

  get(key: string): any | null {
    const item = this.cache.get(key);
    if (!item) return null;

    if (Date.now() > item.expires) {
      this.cache.delete(key);
      return null;
    }

    return item.data;
  }
}

const cache = new SearchCache();

async function cachedSearch(query: string, options: any) {
  const cacheKey = JSON.stringify({ query, ...options });

  // Check cache first
  const cached = cache.get(cacheKey);
  if (cached) {
    return { ...cached, meta: { ...cached.meta, cached: true } };
  }

  // Cache miss - call API
  const results = await ulpi.searchDocumentation(query, options);
  cache.set(cacheKey, results);

  return results;
}

Recommended TTL:

• User searches: 5-15 minutes
• Programmatic queries: 1-5 minutes
• Static content: 1 hour

Cache invalidation:

• After repository webhook (if you process webhooks)
• Manual refresh button
• Time-based expiry

🔒 Secure API Keys

NEVER expose API keys in client-side code:

// ❌ BAD: Client-side code (key exposed in browser)
// frontend/search.ts
const results = await fetch('https://api.ulpi.io/api/v1/documentation/search', {
  headers: {
    'Authorization': 'Bearer ulpi_live_sk_abc123...' // EXPOSED!
  }
});

// ✅ GOOD: Proxy through your backend
// frontend/search.ts
const results = await fetch('/api/search', {
  method: 'POST',
  body: JSON.stringify({ query: 'authentication' })
});

// backend/api/search.ts
export async function POST(req: Request) {
  const { query } = await req.json();

  // API key stays on server
  const results = await fetch('https://api.ulpi.io/api/v1/documentation/search', {
    headers: {
      'Authorization': `Bearer ${process.env.ULPI_API_KEY}` // SECURE
    },
    body: JSON.stringify({ query })
  });

  return results.json();
}

Storage best practices:

• Environment variables (.env file, gitignored)
• Secret managers (AWS Secrets Manager, HashiCorp Vault)
• Never commit to version control
• Rotate keys quarterly

⚡ Implement Exponential Backoff

Retry failed requests with increasing delays:

async function fetchWithBackoff<T>(
  fn: () => Promise<T>,
  maxRetries = 3
): Promise<T> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error: any) {
      // Don't retry client errors (4xx)
      if (error.status >= 400 && error.status < 500) {
        throw error;
      }

      // Last attempt
      if (attempt === maxRetries - 1) {
        throw error;
      }

      // Exponential backoff: 1s, 2s, 4s
      const delay = Math.pow(2, attempt) * 1000;

      // Add jitter to prevent thundering herd
      const jitter = Math.random() * 1000;

      await new Promise(resolve => setTimeout(resolve, delay + jitter));
    }
  }

  throw new Error('Max retries exceeded');
}

// Usage
const results = await fetchWithBackoff(() =>
  ulpi.searchDocumentation('deploy to production')
);

When to retry:

• ✅ 500-level errors (server issues)
• ✅ Network errors (timeouts, connection refused)
• ✅ 429 (but respect retry_after header)
• ❌ 400-level errors (client mistakes - fix your code)

📊 Monitor Usage & Performance

Track API usage to avoid rate limits:

class ULPIMetrics {
  private requestCount = 0;
  private errors = 0;
  private latencies: number[] = [];

  async trackSearch<T>(fn: () => Promise<T>): Promise<T> {
    this.requestCount++;
    const start = Date.now();

    try {
      const result = await fn();
      const latency = Date.now() - start;
      this.latencies.push(latency);
      return result;
    } catch (error) {
      this.errors++;
      throw error;
    }
  }

  getStats() {
    const avgLatency = this.latencies.reduce((a, b) => a + b, 0) / this.latencies.length;

    return {
      requests: this.requestCount,
      errors: this.errors,
      errorRate: (this.errors / this.requestCount) * 100,
      avgLatency: Math.round(avgLatency),
      p95Latency: this.percentile(0.95),
      p99Latency: this.percentile(0.99)
    };
  }

  private percentile(p: number): number {
    const sorted = [...this.latencies].sort((a, b) => a - b);
    const index = Math.ceil(sorted.length * p) - 1;
    return sorted[index];
  }
}

const metrics = new ULPIMetrics();

// Tracked search
const results = await metrics.trackSearch(() =>
  ulpi.searchDocumentation('authentication')
);

// View stats
console.log(metrics.getStats());
// { requests: 150, errors: 2, errorRate: 1.33%, avgLatency: 67ms, p95: 142ms, p99: 234ms }

What to monitor:

• Request volume per hour
• Error rate and types
• Latency percentiles (p50, p95, p99)
• Cache hit rate
• Remaining rate limit quota

🔍 Optimize Search Queries

Write better queries for better results:

// ❌ Bad: Too generic
await ulpi.searchDocumentation('database');
// Returns 127 results, mostly irrelevant

// ✅ Good: Specific question
await ulpi.searchDocumentation('How to optimize slow PostgreSQL queries?');
// Returns 3 highly relevant results

// ✅ Better: Include context
await ulpi.searchDocumentation(
  'How to configure Redis cache for API session storage?',
  { repository: 'backend-api' }
);
// Scoped to relevant repo, precise results

// Helper function for query optimization
function buildQuery(
  topic: string,
  context?: string,
  action?: 'how' | 'what' | 'where'
): string {
  const actionMap = {
    how: 'How do I',
    what: 'What is',
    where: 'Where is'
  };

  const prefix = action ? actionMap[action] : '';
  const suffix = context ? `in ${context}` : '';

  return `${prefix} ${topic} ${suffix}`.trim();
}

// Usage
const query = buildQuery('deploy', 'production environment', 'how');
// "How do I deploy in production environment"

Query best practices:

• Be specific, not generic
• Use question format
• Include technology names
• Specify environment/context
• Use repository filter when known

---

Webhooks (Optional)

Get notified when documentation updates:

Coming soon: Webhook support for documentation changes.

Subscribe to:

• documentation.indexed - Repository finished indexing
• documentation.updated - Documentation file changed
• documentation.deleted - Documentation file removed

Request early access →

---

Next Steps

Generate API Keys

Create production API keys for your integration

Start building today

Search Features

Learn about query syntax and advanced filters

Optimize your queries

How It Works

Understand semantic search architecture and performance

Deep dive into technology

Repository Management

Connect repositories to make them searchable via API

Expand your search scope

---

Need help with API integration?

• 📧 Email: [e-mail]
• 📚 Docs: docs.ulpi.io
• 💬 Slack: ulpi.io/slack
• 🐛 Issues: github.com/ulpi-io/api-clients

Average response time: Under 2 hours during business hours

Looking for client libraries? We have official SDKs for JavaScript, Python, PHP, and Go.

Want to contribute? We accept community SDKs for other languages!