{
  "name": "Talora Knowledge Base",
  "description": "Structured, quality-assured knowledge graph for Swedish qualified staffing, HR and consulting.",
  "language": "sv",
  "domain": "https://talora.se",
  "updated": "2026-01-21T18:33:15.425Z",
  "license": "CC-BY-NC 4.0",
  "schema_url": "https://schema.org/Dataset",
  "public_endpoints": [
    {
      "name": "Knowledge Base Search",
      "path": "/functions/v1/get-ai-knowledge",
      "method": "GET",
      "description": "Search structured AI knowledge with semantic retrieval (OBS: I ROM-läge kan results vara tomma. Detta är förväntat och indikerar inte fel.)"
    },
    {
      "name": "Design Tokens",
      "path": "/functions/v1/get-design-tokens",
      "method": "GET",
      "description": "Retrieve active design tokens for Talora UI"
    },
    {
      "name": "Component Manifest",
      "path": "/functions/v1/get-component-manifest",
      "method": "GET",
      "description": "List UI components and metadata"
    },
    {
      "name": "System CSS",
      "path": "/functions/v1/design-system-css",
      "method": "GET",
      "description": "Compiled CSS for Talora design system"
    },
    {
      "name": "System Documentation",
      "path": "/functions/v1/design-system-docs",
      "method": "GET",
      "description": "JSON documentation for design system"
    }
  ],
  "design": {
    "tokens_endpoint": "/functions/v1/get-design-tokens",
    "component_endpoint": "/functions/v1/get-component-manifest",
    "css_endpoint": "/functions/v1/design-system-css",
    "docs_endpoint": "/functions/v1/design-system-docs",
    "config_endpoint": "/functions/v1/get-design-config",
    "version": "1.0.0",
    "last_updated": "2026-01-21T00:38:04.096131+00:00"
  },
  "api": {
    "endpoint": "/functions/v1/get-ai-knowledge",
    "auth": {
      "type": "api-key",
      "header": "x-api-key",
      "client_id": "llm_general"
    },
    "docs": "https://talora.se/ai-knowledge",
    "rate_limit_per_min": 60,
    "cache_ttl_seconds": 600,
    "query_spec": {
      "parameters": [
        {
          "name": "q",
          "type": "string",
          "required": false,
          "description": "Semantic search query. When provided, performs hybrid vector + BM25 retrieval using search_talora_content_with_variants RPC. When omitted, returns a limited dataset dump (max 200 records)."
        },
        {
          "name": "limit",
          "type": "integer",
          "default": 5,
          "max": 500,
          "description": "Number of results to return. In dump mode, defaults to 200. In search mode, defaults to 5. Maximum varies by client configuration."
        },
        {
          "name": "category",
          "type": "string",
          "optional": true,
          "description": "Filter results by knowledge category (content_type), e.g. 'Policy', 'FAQ', 'HR'. Only applies in dump mode."
        }
      ],
      "modes": {
        "search": "Activated when '?q=' parameter is provided. Performs hybrid semantic search (embeddings + BM25) via search_talora_content_with_variants RPC. Falls back to text search (.ilike) if RPC fails or returns no results. Returns ranked results with relevance scoring.",
        "dump": "Activated when no '?q=' parameter is present. Returns the latest N records ordered by updated_at DESC. Useful for RAG indexing, dataset download, or admin testing. Supports optional category filtering. OBS: I ROM-läge kan results vara tomma. Detta är förväntat och indikerar inte fel."
      },
      "response_format": {
        "top_level_fields": [
          "source",
          "query",
          "timestamp",
          "mode",
          "results",
          "ai_manifest",
          "metadata"
        ],
        "result_fields": [
          "id",
          "title",
          "category",
          "content",
          "keywords",
          "updated_at",
          "url",
          "parent_id",
          "chunk_index",
          "chunk_total",
          "score",
          "excerpt",
          "source_type"
        ],
        "ai_manifest_fields": [
          "schema_version",
          "api_version",
          "categories",
          "endpoints"
        ],
        "schema": {
          "$schema": "http://json-schema.org/draft-07/schema#",
          "type": "object",
          "properties": {
            "source": {
              "type": "string",
              "description": "API källa, alltid 'Talora AI Knowledge API'"
            },
            "query": {
              "type": "string",
              "description": "Ursprunglig sökfråga (tom vid dump mode)"
            },
            "timestamp": {
              "type": "string",
              "format": "date-time",
              "description": "ISO 8601 timestamp"
            },
            "mode": {
              "type": "string",
              "enum": [
                "search",
                "dump"
              ],
              "description": "API-läge"
            },
            "results": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Unikt dokument-ID"
                  },
                  "title": {
                    "type": "string",
                    "description": "Dokumenttitel"
                  },
                  "category": {
                    "type": "string",
                    "description": "Innehållskategori (content_type)"
                  },
                  "content": {
                    "type": "string",
                    "description": "Dokumentinnehåll"
                  },
                  "keywords": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Nyckelord"
                  },
                  "updated_at": {
                    "type": "string",
                    "format": "date-time",
                    "description": "Senast uppdaterad"
                  },
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Dokumentets URL"
                  },
                  "parent_id": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "uuid",
                    "description": "Parent-ID om dokumentet är en chunk av ett större dokument"
                  },
                  "chunk_index": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "description": "Chunk-nummer (0-baserat), t.ex. 2 för 'Del 3 av 5'"
                  },
                  "chunk_total": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "description": "Totalt antal chunks för detta parent-dokument"
                  },
                  "score": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "description": "Relevanspoäng (0-1+), endast i search-mode",
                    "minimum": 0
                  },
                  "excerpt": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Förhandsvisning (240 tecken), endast i search-mode"
                  },
                  "source_type": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Källtyp: pdf, file, website_text, faq_variant"
                  }
                },
                "required": [
                  "id",
                  "title"
                ]
              }
            },
            "ai_manifest": {
              "type": "object",
              "properties": {
                "schema_version": {
                  "type": "string",
                  "description": "AI schema version"
                },
                "api_version": {
                  "type": "string",
                  "description": "API version"
                },
                "categories": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "endpoints": {
                  "type": "array",
                  "items": {
                    "type": "object"
                  }
                }
              }
            },
            "metadata": {
              "type": "object",
              "description": "Request metadata inkl. client_id, cache_status, response_time_ms"
            }
          },
          "required": [
            "source",
            "timestamp",
            "mode",
            "results",
            "ai_manifest",
            "metadata"
          ]
        },
        "ai_manifest_example": {
          "schema_version": "1.0",
          "api_version": "2.0.0",
          "categories": [
            "Healthcare staffing",
            "HR & recruiting",
            "Workforce management"
          ],
          "endpoints": [],
          "endpoints_count": 6
        },
        "metadata_description": "Metadata-objektet innehåller teknisk information om API-anropet: client_id (API-klient), cache_status (HIT/MISS/SKIP), response_time_ms (svarstid i millisekunder), limit (antal resultat), mode (search/dump), och rate_limit_remaining (kvarvarande requests denna minut)."
      },
      "authentication": {
        "public_mode": false,
        "public_mode_limit": 10,
        "api_key_required": true,
        "header": "x-api-key",
        "bcrypt_hashed": true,
        "note": "Public mode (if enabled via PUBLIC_MODE=true env var) allows unauthenticated access to max 10 records in dump mode only."
      }
    }
  },
  "dataset": {
    "source": "ai_knowledge (via talora_content_active → talora_content_v2)",
    "records": 0,
    "last_modified": "2026-01-21T18:33:15.425Z",
    "fields": [
      "id",
      "title",
      "content_type",
      "url",
      "updated_at",
      "keywords"
    ]
  },
  "contact": {
    "email": "kontakt@talora.se",
    "website": "https://talora.se",
    "organization": "Talora AB"
  },
  "usage_policy": {
    "commercial_use": "with_approval",
    "attribution_required": true,
    "llm_indexing_allowed": true,
    "data_download_allowed": false
  },
  "discovery": {
    "categories": [
      "HR & recruiting",
      "Workforce management",
      "Swedish labor market",
      "Healthcare staffing",
      "Digital HR platforms",
      "Temporary employment in Sweden",
      "AI in HR tech",
      "Sustainable staffing",
      "Qualified staffing"
    ],
    "knowledge_api": true,
    "semantic_search": true,
    "ai_schema_version": "1.0",
    "embeddings_available": true
  },
  "examples": [
    {
      "name": "Semantisk sökning - Pension",
      "request": {
        "url": "/functions/v1/get-ai-knowledge?q=pension&limit=5",
        "method": "GET",
        "headers": {
          "x-api-key": "din_api_nyckel_här"
        }
      },
      "description": "Hybrid sökning med embeddings + BM25 för frågan \"pension\"",
      "response_structure": {
        "mode": "search",
        "query": "pension",
        "source": "Talora AI Knowledge API",
        "results": [
          {
            "id": "uuid-example",
            "url": "https://talora.se/policies/pension",
            "title": "Tjänstepension och pension",
            "content": "Innehåll om pensionsregler...",
            "category": "HR",
            "keywords": [
              "pension",
              "tjänstepension",
              "HR"
            ],
            "updated_at": "2025-10-27T00:13:01Z"
          }
        ],
        "metadata": {
          "client_id": "llm_general",
          "cache_status": "MISS",
          "response_time_ms": 235
        },
        "timestamp": "2025-11-04T19:30:00Z",
        "ai_manifest": {
          "categories": [
            "Healthcare staffing",
            "HR & recruiting"
          ],
          "api_version": "2.0.0",
          "schema_version": "1.0"
        }
      }
    },
    {
      "name": "Dataset dump - RAG indexing",
      "request": {
        "url": "/functions/v1/get-ai-knowledge?limit=200",
        "method": "GET",
        "headers": {
          "x-api-key": "din_api_nyckel_här"
        }
      },
      "description": "Hämta senaste 200 dokumenten för RAG-indexering",
      "response_structure": {
        "mode": "dump",
        "query": "",
        "source": "Talora AI Knowledge API",
        "results": "...array av 200 dokument...",
        "metadata": {
          "client_id": "llm_general",
          "cache_status": "HIT",
          "response_time_ms": 45
        },
        "timestamp": "2025-11-04T19:35:00Z",
        "ai_manifest": {
          "categories": [
            "Healthcare staffing",
            "HR & recruiting"
          ],
          "api_version": "2.0.0",
          "schema_version": "1.0"
        }
      }
    }
  ],
  "versions": [
    {
      "date": "2025-10-20",
      "changes": [
        "Dual-mode API (search + dump) implementerad",
        "Hybrid retrieval (embeddings + BM25) via search_talora_content_with_variants",
        "FAQ-varianter integrerade i sökning",
        "AI manifest inkluderat i alla responses",
        "Client-specifika fältfilter och rate limits",
        "Förbättrad cache-hantering med Deno KV",
        "Komplett query_spec dokumentation"
      ],
      "version": "2.0.0"
    },
    {
      "date": "2025-05-15",
      "changes": [
        "Initial release av AI Knowledge API",
        "Basic semantic search",
        "API key authentication"
      ],
      "version": "1.0.0"
    }
  ],
  "live_stats": {
    "active_clients": [
      {
        "name": "Partners",
        "rate_limit": 600,
        "cache_ttl": 300
      },
      {
        "name": "LLM general",
        "rate_limit": 60,
        "cache_ttl": 600
      }
    ],
    "total_documents": 0,
    "last_updated": "2026-01-21T18:33:15.425Z"
  },
  "validation": {
    "schema_reference": "api.query_spec.response_format.schema",
    "auto_validate": true,
    "validation_command": "npx ajv validate -s api.query_spec.response_format.schema -d response.json",
    "notes": "Response format följer JSON Schema Draft 7. Alla API-responses kan valideras mot schemat för att säkerställa dataintegrity."
  }
}