lock Authentication

How to authenticate your API requests. Most endpoints require a Bearer token or Basic Auth.

Bearer Token

curl -X POST https://search.needle.tools/api/ask \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_SECRET_KEY" \
  -d '{"question": "How do I get started?"}'

Set the API_SECRET_KEY env var to enable bearer token authentication.

search Search

Full-text search across all messages and documents.

Example

curl "https://search.needle.tools/api/search?q=help" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "messages": [
    {
      "id": "...",
      "content": "message text",
      "timestamp": "2024-01-01T00:00:00Z",
      "username": "user",
      "channelName": "general",
      "channelSlug": "general",
      "platformName": "My Server",
      "platformType": "discord"
    }
  ],
  "documents": [
    {
      "id": "...",
      "title": "Doc Title",
      "slug": "doc-title",
      "content": "full content..."
    }
  ]
}

manage_search Semantic Search

Embedding-based semantic search. Returns ranked results with full content — no LLM in the loop. Designed for MCP tools, CLI, and AI agents.

Parameters

Example

curl "https://search.needle.tools/api/semantic-search?q=how+to+add+physics&limit=5" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response

{
  "query": "how to add physics",
  "results": [
    {
      "type": "document",
      "score": 0.87,
      "title": "Physics Components",
      "source": "Needle Engine Docs",
      "content": "full text of the matched chunk...",
      "contentLength": 4820,
      "truncated": true,
      "url": "https://engine.needle.tools/docs/physics#:~:text=..."
    }
  ],
  "durationMs": 142
}

smart_toy Ask AI

Ask a question using AI with RAG over indexed content. Supports streaming (SSE) and plain JSON responses.

Request body

{
  "question": "What is the main topic discussed?",
  "messages": [                          // optional — conversation history
    { "role": "user",      "content": "Previous question" },
    { "role": "assistant", "content": "Previous answer"  }
  ]
}

Streaming (SSE)

curl -X POST https://search.needle.tools/api/ask \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: text/event-stream" \
  -d '{"question": "What is the main topic discussed?"}'

Events emitted:

data: {"type":"sources","sources":[...]}
data: {"type":"token","token":"Based "}
data: {"type":"token","token":"on the..."}
data: {"type":"done","usage":{"prompt_tokens":1420,"completion_tokens":312,"total_tokens":1732}}

JSON

curl -X POST https://search.needle.tools/api/ask \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"question": "What is the main topic discussed?"}'

{
  "answer": "Based on the indexed content...",
  "sources": [
    {
      "type": "message",
      "score": 0.89,
      "metadata": "user in #general",
      "preview": "message preview...",
      "sourceUrl": "https://..."
    }
  ],
  "usage": { "prompt_tokens": 1420, "completion_tokens": 312, "total_tokens": 1732 }
}

terminal Machine-Readable

Plain text documentation for LLMs and AI agents.

Describes available endpoints, parameters, and auth in a format optimized for AI agents.