API Documentation

Endpoints are split into three access levels:

Bearer Token Example

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

Admin Bearer Token Example

curl -X POST https://finder.cloud-staging.needle.tools/api/sources/PLATFORM_ID/crawl \
  -H "Authorization: Bearer YOUR_API_SECRET_KEY"

Set API_SECRET_KEY env var to enable bearer token authentication. All POST, PATCH, and DELETE endpoints accept either Basic Auth or Authorization: Bearer <token>.

Full-text search across all messages and documents.

Example

curl "https://finder.cloud-staging.needle.tools/api/search?q=help"

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..."
    }
  ]
}

Ask a question using AI with RAG over indexed content. Used by the internal UI.

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

Public AI Ask API for external integrations. Requires Authorization: Bearer <token> header matching API_SECRET_KEY env var.

Response

{
  "answer": "Based on the indexed content...",
  "sources": [
    {
      "type": "message",
      "score": 0.89,
      "metadata": "user in #general (Discord) at 2024-01-01",
      "preview": "message preview..."
    }
  ]
}

List all configured sources. Requires Basic Auth or Bearer token.

Add a new source. Requires Basic Auth or Bearer token.

Update a source. Requires Basic Auth or Bearer token.

Delete a source and all its data. Requires Basic Auth or Bearer token.

Trigger a crawl for a source. Add ?full=true to recrawl all messages from the beginning. Requires Basic Auth or Bearer token.

Response

{"jobId": "...", "channels": 15, "messages": 1234}

Test connection to a source. Requires Basic Auth or Bearer token.

List all documents.

Upload a document (multipart form data). Requires Basic Auth or Bearer token.

Browse all sources — channels, documents, and web content.

View a channel's messages.

View a document's content.

Sitemap index.

Plain text documentation for LLMs and AI agents.