Developer API Reference | SciFork Insight

Overview & Authentication

The SciFork Insight Developer API is stateless, permitting developers to issue queries and get grounded responses directly without managing session or conversation histories.

All API requests must route through HTTPS and are authenticated using a custom API Key sent via the X-API-Key request header.

Managing API Keys:
API Keys can be generated, previewed, and revoked by account managers directly in the web application. Navigate to Settings → API Access in your SciFork Insight dashboard to retrieve your key. Ensure keys are stored securely; they are only shown once during creation.

Authentication Headers

HTTP Headers

X-API-Key: sk_scifork_YOUR_API_KEY
Content-Type: application/json

API Base URL

Production Endpoint Base

https://api.insight.scifork.com

Query Knowledge Bases

Submit queries to retrieve document-grounded answers generated directly from your indexed knowledge bases.

POST /api/v1/query

Request Body Parameters

Field	Description
query string required	The question or prompt text you wish to search across the knowledge bases.
kb_ids array of strings optional	An array of Knowledge Base IDs to restrict the query search. If omitted or empty, the API automatically queries all knowledge bases currently marked as selected in your dashboard settings.

Response Fields

Field	Description
answer string	The generated response, complete with bracketed inline citation indices (e.g. `[1]`, `[2]`) mapping directly to the `references` array.
references array of objects	List of document chunks cited in the answer. Each object contains: `index` (integer): The citation label number. `filename` (string): Source document name. `link` (string): Temporary GCS signed URL to download/view the document (expires in 6 hours). `chunk` (object): The citation grounding details containing `content` (string snippet) and `page_start` (string page identifier).
credits integer	The updated remaining credit balance on your account. Each API query consumes 1 credit.

Request Example

curl -X POST "https://api.insight.scifork.com/api/v1/query" \
  -H "X-API-Key: sk_scifork_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the core metrics?",
    "kb_ids": ["kb_123456"]
  }'

fetch("https://api.insight.scifork.com/api/v1/query", {
  method: "POST",
  headers: {
    "X-API-Key": "sk_scifork_YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    query: "What are the core metrics?",
    kb_ids: ["kb_123456"]
  })
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error("Error:", error));

import requests

url = "https://api.insight.scifork.com/api/v1/query"
headers = {
    "X-API-Key": "sk_scifork_YOUR_API_KEY",
    "Content-Type": "application/json"
}
payload = {
    "query": "What are the core metrics?",
    "kb_ids": ["kb_123456"]
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Response Example

JSON 200 OK

{
  "answer": "SciFork's core metrics include revenue growth [1] and operational efficiency [2].",
  "references": [
    {
      "index": 1,
      "filename": "Q2_Report.pdf",
      "link": "https://storage.googleapis.com/... (GCS Signed Link)",
      "chunk": {
        "content": "Revenue grew by 24% year-over-year during the second quarter.",
        "page_start": "4"
      }
    },
    {
      "index": 2,
      "filename": "Operations_Overview.pdf",
      "link": "https://storage.googleapis.com/... (GCS Signed Link)",
      "chunk": {
        "content": "Operational efficiency increased by streamlining the pipeline.",
        "page_start": "11"
      }
    }
  ],
  "credits": 99
}

Error Handling

The API uses standard HTTP response codes to indicate the success or failure of an API request. In general, 2xx status codes indicate success, 4xx status codes indicate an error from the client-side inputs, and 5xx status codes indicate an issue with SciFork's servers.

HTTP Code	Error Message / Cause
400 Bad Request	query is required: The request payload is missing the mandatory `query` field, or it was left blank.
401 Unauthorized	Missing or invalid X-API-Key: The key provided in the `X-API-Key` header is incorrect, revoked, or the header was omitted entirely.
402 Payment Required	Insufficient credits / Quota exhausted: Your workspace has run out of query credits. Purchase additional credits through the billing page, or contact the account manager.
403 Forbidden	Storage limits exceeded / Plan expired: Your workspace storage usage exceeds the indexed storage limits of your current plan, or your promotional plan has reached its expiration date.
500 Server Error	Internal Server Error: An unexpected error occurred while processing retrieval or synthesizing the response on the server.

Error Response Example

JSON 401 Unauthorized

{
  "error": "Invalid API Key",
  "message": "Please provide a valid X-API-Key header."
}