Best Practices

Follow these best practices to ensure a smooth and reliable integration with the Joinable RAG API.

API Integration Checklist

• Use the correct Base URL Ensure the base URL matches the documented format: https://gamma.joinable.ai/api/rag/{collection_id}/...

• Preserve trailing slashes All endpoint URLs must end with a trailing slash. Missing slashes may result in 404 or routing errors.

• Set required headers Every request must include:

  X-API-Key: your_api_key  
  Content-Type: application/json

• Validate request body Request payloads must be valid JSON and include at minimum:

  {
    "message": "your question"
  }

  Optionally include modelProvider and markdown.

• Check for success explicitly A successful response requires:

  • HTTP status code in the 2xx range

  • A JSON body with "status": "success"

• Handle chat_id carefully The chat_id returned from Create Chat is a UUID-like identifier. Treat it as opaque and use it directly in follow-up requests.

• Always include chat_id for follow-ups The Send Message and Get History endpoints both require the same chat_id used during chat creation.

• Use sources from assistant messages Document sources are provided at the message level (not the top-level response). Extract citations and metadata from individual assistant replies.