Developer Portal

Sapere connects you with domain experts — legal, financial, medical, technical, creative, and more. All expert interactions happen via this REST API.

Quick Start

1. Get an API key

curl -X GET https://sapere.polsia.app/api/keys

2. List experts

curl -H "Authorization: Bearer YOUR_KEY" https://sapere.polsia.app/api/experts

3. Consult an expert

curl -X POST https://sapere.polsia.app/api/experts/exp_legal_001/consult \\
  -H "Authorization: Bearer YOUR_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{"question": "What should I include in a SaaS terms of service?"}'

Endpoints

Method	Path	Description
GET	/api/keys	Generate a new API key
GET	/api/experts	List all available experts
POST	/api/query	Query an expert by domain
POST	/api/experts/:id/consult	Consult a specific expert by ID
GET	/health	Health check

GET /api/keys

Generates a new API key. The raw key is returned once — store it securely. Store the key_prefix to identify the key later.

Response

{
  "message": "Store this key securely — it will not be shown again.",
  "key": "sap_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
  "key_prefix": "c3d4",
  "created_at": "2026-06-02T00:00:00.000Z"
}

GET /api/experts

Returns all available expert domains with metadata.

Headers

Authorization: Bearer YOUR_KEY

Response

{
  "experts": [
    {
      "id": "exp_legal_001",
      "name": "Margaret Chen, J.D.",
      "domain": "Legal",
      "specialty": "Corporate Law & Business Contracts",
      "bio": "...",
      "hourly_rate": 450,
      "response_time": "< 2 hours",
      "tags": ["contracts", "incorporation", "IP", "compliance"],
      "avatar_initials": "MC"
    },
    ...
  ],
  "count": 6
}

POST /api/query

Ask a question and route it to the best expert for the given domain. Falls back to the first available expert if no exact domain match.

Headers

Authorization: Bearer YOUR_KEY
Content-Type: application/json

Request body

{
  "domain": "Legal",
  "question": "What should I include in a SaaS terms of service?"
}

Response

{
  "matched_domain": "Legal",
  "expert_id": "exp_legal_001",
  "consultation": {
    "expert_id": "exp_legal_001",
    "expert_name": "Margaret Chen, J.D.",
    "domain": "Legal",
    "question": "What should I include in a SaaS terms of service?",
    "response": "[Mock response from Margaret Chen, J.D.] ...",
    "confidence": 0.87,
    "suggested_follow_ups": [
      "Can you give me a more detailed breakdown for legal contexts?",
      "What are the most common pitfalls in this area?",
      "Are there any recent developments I should be aware of?"
    ],
    "consultation_price": 45,
    "expires_at": "2026-06-03T00:00:00.000Z"
  },
  "alternatives": [
    { "id": "exp_tech_001", "domain": "Technical", "name": "Liam Torres" },
    ...
  ]
}

POST /api/experts/:id/consult

Consult a specific expert by their ID. Returns a structured response with follow-up suggestions.

Headers

Authorization: Bearer YOUR_KEY
Content-Type: application/json

Request body

{
  "question": "What are the key GDPR considerations for a B2B SaaS product?"
}

Response

{
  "consultation": {
    "expert_id": "exp_legal_001",
    "expert_name": "Margaret Chen, J.D.",
    "domain": "Legal",
    "question": "What are the key GDPR considerations for a B2B SaaS product?",
    "response": "[Mock response from Margaret Chen, J.D.] ...",
    "confidence": 0.87,
    "suggested_follow_ups": [...],
    "consultation_price": 45,
    "expires_at": "2026-06-03T00:00:00.000Z"
  }
}

Available Experts

Authentication

All API endpoints (except /api/keys and /health) require a Bearer token.

Authorization: Bearer YOUR_API_KEY

Missing or invalid keys return:

// 401 Unauthorized
{ "error": "Missing API key. Include: Authorization: Bearer " }
// or
{ "error": "Invalid or inactive API key." }

Error Codes

Status	Meaning
400	Bad request — missing or invalid required fields
401	Unauthorized — missing or invalid API key
404	Not found — expert ID does not exist
500	Internal server error

Try It

Run these commands in your terminal to test the API:

# 1. Get a key
curl -X GET https://sapere.polsia.app/api/keys

# 2. List experts
curl -H "Authorization: Bearer YOUR_KEY" https://sapere.polsia.app/api/experts

# 3. Query by domain
curl -X POST https://sapere.polsia.app/api/query \\
  -H "Authorization: Bearer YOUR_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{"domain": "Legal", "question": "What is a reasonable cap table for a seed round?"}'

# 4. Consult a specific expert
curl -X POST https://sapere.polsia.app/api/experts/exp_tech_001/consult \\
  -H "Authorization: Bearer YOUR_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{"question": "How do I scale a PostgreSQL database to 10M rows?"}'