API Discovery

Kiket’s discovery API lets trusted backend services reuse the same semantic search index, quick actions, and natural-language parser that power the command palette. Responses mirror the in-product experience, returning rich metadata, confidence scores, and suggested follow-up actions.

Feature flag: Discovery endpoints respect the smart_search AI feature. Organizations must have the feature enabled (Team plan or higher, plus any org-level overrides) or the API returns 403 feature_disabled.

Authentication

Discovery uses a single shared token: add the header X-Discovery-Token: <token> or Authorization: Bearer <token>. The token must match one of:

• ENV["DISCOVERY_API_TOKEN"]
• Rails.application.credentials.discovery.api_token

Set the secret in your deployment environment and rotate it following your standard secret-management process.

Search Endpoint

GET /api/v1/discovery/search
Content-Type: application/json
X-Discovery-Token: <token>

Query params:
  organization_id (required)
  q                (required, min length 2)
  filter           (all|issues|projects|knowledge|users|insights)
  project_id       (optional: narrow to a specific project)
  limit            (optional: max 50, default 20)
  scope            (optional: pass a custom discovery scope id)

Example request:

curl \
  -H "X-Discovery-Token: $DISCOVERY_API_TOKEN" \
  "https://kiket.dev/api/v1/discovery/search?organization_id=42&q=release+risk"

Example response (truncated):

{
  "query": "release risk",
  "filter": "all",
  "total": 6,
  "results": {
    "issue": [
      {
        "id": 581,
        "entity_type": "issue",
        "title": "Investigate release risk regression",
        "summary": "Ensure rollout blockers are addressed before launch",
        "url": "/issues/581",
        "score": 0.86,
        "confidence": 0.81,
        "metadata": {
          "status": "in_progress",
          "priority": "high",
          "project_id": 12
        },
        "actions": [
          { "label": "Open Issue", "icon": "bi-clipboard-check", "url": "/issues/581" },
          { "label": "Assign", "icon": "bi-person-check", "url": "/issues/581#assignment" }
        ]
      }
    ],
    "knowledge_document": [
      {
        "id": 44,
        "entity_type": "knowledge_document",
        "title": "Release Playbook",
        "summary": "Checklist for the release readiness review",
        "url": "/knowledge/documents/44",
        "confidence": 0.74
      }
    ]
  }
}

• score combines semantic similarity and keyword boosts.
• confidence is the cosine similarity of the embedding match.
• actions mirror the command palette quick actions and can be rendered in your UI.

Intent Parsing Endpoint

POST /api/v1/discovery/interpret
Content-Type: application/json
X-Discovery-Token: <token>

Body:
{
  "organization_id": 42,
  "q": "high priority issues assigned to me due this week",
  "user_id": 17   // optional context actor
}

Response:

{
  "query": "high priority issues assigned to me due this week",
  "filters": {
    "assignee": "17",
    "priority": ["high", "critical"],
    "due_date": {"from": "2025-11-03", "to": "2025-11-09"},
    "search": "high priority issues assigned to me due this week"
  },
  "explanations": [
    "Filtering to issues assigned to Jordan Manager.",
    "Focusing on high and critical priorities.",
    "Due this week."
  ],
  "actor": {
    "id": 17,
    "name": "Jordan Manager",
    "email": "jordan@example.com"
  }
}

Use the filters payload directly with /issues list parameters or persist it via POST /issues/list_views to create a saved view.

Telemetry

Every successful search records a discovery.search usage event (counts only; query text is hashed). You can monitor adoption via usage dashboards or export raw events for deeper analysis.

Error Codes

Status	Code	Meaning
401	unauthorized	Missing or incorrect discovery token.
403	organization_context_missing	organization_id not found or not available.
403	feature_disabled	smart_search feature is off for the target organization.
422	invalid_filter	Provided filter or project scope is invalid (validation).

All other errors follow the generic API error format described in REST API errors.