Crystallise AI Backend API Reference

Returns { "status": "ok" }. No checks — "am I running?" only.

{"status": "ready", "checks": {"database": "ok", "openai_key": "configured"}}

{"status": "degraded", "checks": {"database": "error: connection refused", "openai_key": "missing"}}

Returns a single ServiceConfigResponse. Unknown service_id returns a default config rather than 404.

The updated ServiceConfigResponse (same fields as GET).

curl -s -X PUT http://localhost:8005/v1/config/services/screening \
  -H "X-API-Key: dev-key" -H "Content-Type: application/json" \
  -d '{"model": "gpt-5-mini", "temperature": 0.2}'
# →
{
  "service_id": "screening",
  "model": "gpt-5-mini",
  "temperature": 0.2,
  "max_output_tokens": 8192,
  ...
}

# Request
curl -s -X POST http://localhost:8005/v1/screening/jobs \
  -H "X-API-Key: dev-key" \
  -H "Content-Type: application/json" \
  -d '{
    "papers": [
      {"id": "p1", "title": "RCT of drug X in adults", "abstract": "Randomized trial..."}
    ],
    "criteria": [{"name": "Population", "type": "include", "value": "Adults"}],
    "questions": ["Is drug X effective?"],
    "mock": true
  }'

# Response
{"job_id": "abc-123", "status": "pending", "progress": 0.0, "stage": ""}

{"detail": "Estimated cost $1.23 exceeds max_estimated_cost_usd=$0.50"}

curl -s http://localhost:8005/v1/screening/jobs/abc-123 -H "X-API-Key: dev-key"
# →
{
  "job_id": "abc-123",
  "status": "completed",
  "progress": 1.0,
  "stage": "assignment",
  "results": [{"id": "p1", "final_score": 4.2, "cluster_id": 1, "reasoning": "..."}],
  "clusters": [{"cluster_id": 1, "label": "Eligible RCTs", "count": 1}],
  "duration_ms": 3421,
  "estimated_cost_usd": 0.002
}

Returns the running/pending job for this project_id, or null. Use to dedupe: EM should not start a new job while one is running for the same project.

curl -s -X POST http://localhost:8005/v1/screening/estimate \
  -H "X-API-Key: dev-key" -H "Content-Type: application/json" \
  -d '{"model": "gpt-5-nano", "papers_count": 500, "repetitions": 5, "criteria_count": 10}'
# →
{
  "estimated_input_tokens": 775000,
  "estimated_output_tokens": 75000,
  "estimated_cost_usd": 0.0625,
  "model": "gpt-5-nano",
  "papers_count": 500,
  "repetitions": 5,
  "confidence": "approximate",
  "disclaimer": "Estimate based on empirical averages. Actual cost may vary +-30%..."
}

curl -s -X POST http://localhost:8005/v1/indexer/run \
  -H "X-API-Key: dev-key" -H "Content-Type: application/json" \
  -d '{
    "records": [{"ID": "p1", "Title": "RCT of drug X", "Abstract": "150 adults..."}],
    "fields": [
      {"name": "study_design", "description": "Type of study", "data_type_primary": "text"},
      {"name": "sample_size", "description": "Number of participants", "data_type_primary": "number"}
    ],
    "mode": "test"
  }'
# →
{
  "results": [{
    "ID": "p1",
    "indexing_status": "ok",
    "study_design": {"value": "RCT", "confidence": 0.95, "evidence": [...]},
    "sample_size": {"value": 150, "confidence": 0.9, "evidence": [...]}
  }],
  "errors": [],
  "usage": {"input_tokens": 320, "output_tokens": 85, "total_tokens": 405, "estimated_cost_usd": 0.0002},
  "model_version": "gpt-5-mini-2025-02-01"
}

{"detail": {"message": "...", "error_code": "validation", "retryable": false}}

Identical to POST /v1/indexer/run. Summarised here for completeness.

curl -s -X POST http://localhost:8005/v1/indexer/jobs \
  -H "X-API-Key: dev-key" -H "Content-Type: application/json" \
  -d '{"records": [...], "fields": [...], "mode": "full"}'
# →
{"job_id": "xyz-789", "status": "pending", "progress": 0.0}

Returns the running/pending indexer job for this project_id, or null.

curl -s -X POST http://localhost:8005/v1/indexer/estimate \
  -H "X-API-Key: dev-key" -H "Content-Type: application/json" \
  -d '{"fields": [{"name": "study_design", "description": "...", "data_type_primary": "text"}], "record_count": 100}'
# →
{
  "estimated_input_tokens": 32000,
  "estimated_output_tokens": 8500,
  "estimated_cost_usd": 0.0234,
  "confidence": "approximate",
  "disclaimer": "Estimate based on empirical averages..."
}

curl -s -X POST http://localhost:8005/v1/indexer/suggest-fields \
  -H "X-API-Key: dev-key" -H "Content-Type: application/json" \
  -d '{"project_context": {"description": "RCTs of exercise for depression"}, "mock": true}'
# →
{
  "fields": [
    {"name": "study_design", "description": "Type of study", "data_type_primary": "text", "examples": ["RCT", "cohort"]},
    {"name": "sample_size", "description": "Number of participants", "data_type_primary": "number"}
  ],
  "warnings": []
}

curl -s -X POST http://localhost:8005/v1/indexer/refine-fields \
  -H "X-API-Key: dev-key" -H "Content-Type: application/json" \
  -d '{"fields": [{"name": "outcome", "description": "...", "data_type_primary": "text"}]}'
# →
{
  "suggestions": [
    {"action": "modify", "field": {"name": "primary_outcome", ...}, "rationale": "...",
     "original_field_name": "outcome"}
  ]
}

curl -s -X POST http://localhost:8005/v1/indexer/group-tags \
  -H "X-API-Key: dev-key" -H "Content-Type: application/json" \
  -d '{"field_name": "study_design", "values": ["RCT", "randomised controlled trial", "cohort study", "case-control"]}'
# →
{
  "groups": [
    {"name": "Randomised controlled trials", "values": ["RCT", "randomised controlled trial"], "rationale": "..."},
    {"name": "Observational", "values": ["cohort study", "case-control"], "rationale": "..."}
  ],
  "usage": {"total_tokens": 150, "estimated_cost_usd": 0.0002}
}

curl -s -X POST http://localhost:8005/v1/criteria/analyze-question \
  -H "X-API-Key: dev-key" -H "Content-Type: application/json" \
  -d '{"research_question": "Does exercise help depression?", "mock": true}'
# →
{
  "status": "could_improve",
  "missing_elements": [
    "Population is not specified",
    "Outcome measures are vague"
  ],
  "suggestion": "Mock mode: specify the population, intervention, and primary outcome to make the question searchable. Run without mock for real analysis."
}

{"detail": [{"type": "missing", "loc": ["body", "research_question"], "msg": "Field required"}]}

curl -s -X POST http://localhost:8005/v1/criteria/generate \
  -H "X-API-Key: dev-key" -H "Content-Type: application/json" \
  -d '{"project_description": "RCTs of exercise for depression in adults", "mock": true}'
# →
{
  "criteria": [
    {"category": "Study Design", "text": "Review articles, systematic reviews, meta-analyses", "criterion_type": "exclude", "description": "..."},
    {"category": "Publication Type", "text": "Conference abstracts without full publication", "criterion_type": "exclude", "description": "..."}
  ]
}

curl -s -X POST http://localhost:8005/v1/criteria/picos \
  -H "X-API-Key: dev-key" -H "Content-Type: application/json" \
  -d '{"project_description": "RCTs of metformin vs placebo in adults with type 2 diabetes", "mock": true}'
# →
{
  "elements": {
    "population": "Adults with the condition described in the project",
    "intervention": "The primary intervention or exposure under review",
    "comparison": "Standard of care, placebo, or no intervention",
    "outcome": "Primary clinical outcomes, efficacy, and safety measures",
    "study_design": "Study designs relevant to the research question"
  },
  "gap_flags": ["Mock mode: PICOS elements are placeholders — run without mock for real extraction"],
  "contraindications": []
}

curl -s -X POST http://localhost:8005/v1/criteria/refine-context \
  -H "X-API-Key: dev-key" -H "Content-Type: application/json" \
  -d '{"description": "Review of drug X", "research_questions": ["Is drug X effective?"], "mock": true}'
# →
{
  "refined_description": "Review of drug X\n\n[Refined for clarity and specificity in systematic review screening.]",
  "refined_research_questions": ["Is drug X effective? [refined for precision]"],
  "explanation": "Mock mode: minor refinements applied as placeholders. Run without mock for real AI refinement."
}

curl -s -X POST http://localhost:8005/v1/criteria/refine \
  -H "X-API-Key: dev-key" -H "Content-Type: application/json" \
  -d '{
    "current_criteria": [{"category": "Population", "text": "Adults only"}],
    "conflicts": [{"paper_title": "Study A", "decision_a": "include", "decision_b": "exclude"}],
    "mock": true
  }'
# →
{
  "criteria": [
    {"category": "Study Design", "text": "Exclude retrospective observational studies without a control arm", "criterion_type": "exclude", "confidence": 0.72, "rationale": "Derived from 1 reviewer conflict(s) on study design."},
    {"category": "Outcome Reporting", "text": "Exclude studies that do not report the primary outcome quantitatively", "criterion_type": "exclude", "confidence": 0.65, "rationale": "Pattern across 1 conflict(s) flagged insufficient outcome data."}
  ]
}

curl -s -X POST http://localhost:8005/v1/criteria/consolidate \
  -H "X-API-Key: dev-key" -H "Content-Type: application/json" \
  -d '{"criteria": [{"id": 1, "category": "Population", "text": "Adults 18+"}, {"id": 2, "category": "Population", "text": "Adult participants over 18"}], "mock": true}'
# →
{
  "duplicate_groups": [],
  "consolidation_proposals": [],
  "warnings": ["Mock mode: no consolidation performed"]
}