Skip to content

API Reference Overview

Welcome to the comprehensive API Reference for our advanced Indexing, Search, and Inference API. This powerful suite of endpoints enables you to manage documents, perform sophisticated searches, and leverage AI-powered inference capabilities across your data.

Core Functionalities

Our API is organized into three main sections, each offering robust capabilities:

  1. Indexing: Efficiently manage your document collection
  2. Search: Execute powerful, multi-faceted searches across indexed documents
  3. Inference: Harness AI-driven tasks for intelligent data processing

Base URL

All API requests should be directed to:

https://api.example.com/v1

Authentication

Secure your API requests using an API key. Include your unique key in the Authorization header for all requests:

Authorization: Bearer YOUR_API_KEY

Response Format

Our API consistently returns responses in JSON format. Successful responses typically include a data field containing the requested information, while error responses include an error field with detailed error information.

Rate Limiting

To ensure fair usage and optimal performance, we employ rate limiting:

  • 100 requests per minute
  • 5000 requests per day

Exceeding these limits will result in a 429 Too Many Requests response.

Detailed Endpoint Overview

Indexing

Efficiently manage your document collection with these endpoints:

  1. Index Document (POST /index)
  2. Add new documents to the indexing queue
  3. Support for various data types: URLs, base64 encoded data, plain text, and structured data

  4. Customizable metadata for enhanced document management

  5. Get Index Status (GET /index_status)

  6. Track the status of indexed documents

  7. Possible statuses: queued, processing, indexed, failed

  8. Delete Document (DELETE /delete)

  9. Remove documents from the index or indexing queue
  10. Useful for managing outdated content or compliance with data retention policies

Execute powerful searches across your indexed documents:

  • Search Documents (GET /search)
  • Multiple search types: dense, sparse, graph, hybrid_vector, hybrid_vector_graph
  • Customizable search spaces: global, textual_content, media, custom_file_type, custom_file_extension
  • Advanced filtering and pagination capabilities
  • Relevance scoring for accurate result ranking

Inference

Leverage AI-powered tasks with our inference endpoints:

  • Infer (POST /infer)

  • Supports multiple inference types:

    1. Chat Inference:
    2. Simulates chat interactions with an AI assistant
    3. Incorporates user history, search results, and external context
    4. Provides referred context with relevancy scores
    5. Summarize Inference:
    6. Generates concise summaries of various content types
    7. Supports text, documents, images, and web pages
    8. Customizable summary length and focus
    9. Smart Chips Inference:
    10. Extracts bite-sized information from various contexts
    11. Generates FAQ pairs and suggested queries
    12. Enhances user engagement with personalized information chips

  • Flexible streaming options: disabled, enabled, per_value

  • Specialized model selection for tailored inference tasks

Best Practices

  1. Use appropriate search types and spaces for optimal performance and accuracy
  2. Leverage metadata and additional filters in searches for precise results
  3. Utilize chat session IDs and user IDs (surf_id) for personalized experiences in chat inference
  4. Take advantage of streaming responses for real-time data processing

Error Handling

Our API uses standard HTTP response codes. Common errors include:

  • 400 Bad Request: Invalid input data
  • 401 Unauthorized: Missing or invalid API key
  • 404 Not Found: Resource not found
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Unexpected server-side issues

Detailed error messages are provided in the response body to aid in troubleshooting.

Conclusion

This API offers a powerful set of tools for document management, advanced search capabilities, and AI-driven inference tasks. By effectively utilizing these endpoints, you can create sophisticated, intelligent applications that process and analyze data with unprecedented efficiency and insight.

For detailed information on request parameters, response formats, and example usage for each endpoint, please refer to the specific documentation sections linked in this overview.