lock Authentication

Search and Ask are public — no token needed, but rate-limited. A Bearer token lifts the rate limit and unlocks the rest of the API.

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.

If exact matching finds nothing, short keyword queries can use a bounded one-edit typo fallback over the indexed vocabulary. Advanced FTS expressions and words shorter than four letters keep exact matching.

Web pages are deduplicated across chunks and Needle Engine API versions. Use source to search one platform by name (for example, Needle Engine Docs). Add visibility=public to exclude hidden sources even with a bearer token. Source-filtered searches return platform messages, not uploaded 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"

No token required. Add -H "Authorization: Bearer YOUR_TOKEN" to lift the 10 requests/min rate limit.

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 "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" \
  -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.