API Reference

Authentication

Seahorse uses JWT tokens for authentication. After registering or logging in, include the token in the Authorization header of every request:

Authorization: Bearer YOUR_JWT_TOKEN

Alternatively, you can use your API key (prefixed with sh_) in the same header:

Authorization: Bearer sh_YOUR_API_KEY

JWT tokens expire after 72 hours. API keys do not expire but can be regenerated (which invalidates the previous key).

Response Format

All responses are JSON. Errors return a detail field:

{
  "detail": "Invalid credentials"
}

Rate Limits

Authentication endpoints (/v1/auth/register, /v1/auth/login) are rate-limited to 10 requests per minute per IP address. Other endpoints are not rate-limited.

Auth Endpoints

No authentication required.

RAG Connection

Documents

PDF Upload

Chunk quotas by tier: Free 100, Starter 5,000, Pro 50,000, Enterprise unlimited.

Cognitive Engine

Write-back

Smart Query

Chat

The chat endpoint accepts an optional sources parameter:

{
  "message": "What are my orphan documents?",
  "sources": "all"
}

Values: "pdf" (uploaded PDFs only), "rag" (connected vector DB only), "all" (both, default). Responses include a citations array with source file name, page number, and relevant excerpt.

Billing

Examples

Register

curl -X POST https://seahorse.tools/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'

Returns: {"token": "eyJ...", "client_id": "abc123", "api_key": "sh_..."}

Login

curl -X POST https://seahorse.tools/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'

Returns: {"token": "eyJ...", "client_id": "abc123"}

Connect Your RAG

curl -X POST https://seahorse.tools/api/v1/connect \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "qdrant",
    "url": "https://your-qdrant.example.com:6333",
    "collection_name": "my-docs"
  }'

For Pinecone, use "provider": "pinecone" and include "api_key": "...".

Trigger a Cognitive Cycle

curl -X POST https://seahorse.tools/api/v1/cognitive/cycle \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tier": "free"}'

Returns: {"job_id": "uuid-here", "status": "running"}. Poll with GET /v1/cognitive/cycle/{job_id}.

Upload a PDF

curl -X POST https://seahorse.tools/api/v1/upload \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@document.pdf"

Returns: {"chunks_created": 42, "document_id": "doc_..."}. Single-file uploads also create an editable document.

Chat (with source filter)

curl -X POST https://seahorse.tools/api/v1/chat \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "What are my orphan documents?", "sources": "all"}'

Returns: {"response": "Based on the latest analysis...", "citations": [{"source": "guide.pdf", "page": 3, ...}]}

Analyze a Single Document

curl -X POST https://seahorse.tools/api/v1/documents/doc_abc123/analyze \
  -H "Authorization: Bearer $TOKEN"

Returns: {"job_id": "uuid-here", "status": "running"}. Runs the 8-phase cognitive cycle scoped to one document.

Smart Query

curl -X POST https://seahorse.tools/api/v1/query \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "How does our onboarding process work?"}'

Returns a compressed briefing with source references from your RAG.