HTTP API

Exact FastAPI route families, request boundaries, authentication, caching, and default-off workflow execution.

Start the optional [service] app from a source checkout:

RAGSPINE_DB_PATH=data/fact_metric.db \
  .venv/bin/python scripts/run_server.py --port 8000

Engine routes

Method	Path	Request / behavior
`GET`	`/healthz`	liveness
`GET`	`/readyz`	fact-store and optional queue readiness; `503` when degraded
`POST`	`/v1/ask`	`question`, optional `reference_date`, optional `(role, text)` `history`
`POST`	`/v1/ask/stream`	same completed guarded answer over SSE
`POST`	`/v1/ingest/structured/jobs`	`.xlsx`, `.xlsm`, `.pptx`, `.pdf` job
`POST`	`/v1/ingest/narrative/jobs`	`.pptx`, `.pdf` job
`GET`	`/v1/jobs/{job_id}`	queue status/result/error
`GET`	`/v1/topology?scope=agent\|service`	static engine topology; invalid scope returns `400`

Example:

curl -s http://127.0.0.1:8000/v1/ask \
  -H 'content-type: application/json' \
  -d '{"question":"China FY2024 revenue","history":[["user","Use the annual report"]]}'

/v1/ask/stream first computes the complete guarded response, then sends start, zero or more delta, and done SSE frames. A guard failure therefore cannot be half-streamed and retracted.

Query fields are offset (default 0) and limit (1–100, default 100). The response contains total, offset, limit, nullable next_offset, and metadata-only templates. It intentionally omits workflow YAML and preview data.

The route sends a weak page-specific ETag and Cache-Control: public, max-age=300, stale-while-revalidate=3600. A matching If-None-Match may receive 304.

`GET /v1/workflow-templates/{template_id}`

Returns catalog metadata plus canonical workflow, deterministic Dify yaml, and display-only preview schema version 1. An unknown identifier returns 404 without exposing paths.

`POST /v1/workflow-scaffold`

{ "description": "invoice extraction and approval", "reuse": true }

description is 1–4,096 characters. Optional template_id must be a lowercase hyphenated catalog identifier. Extra fields are forbidden. The response contains workflow, yaml, preview, origin, template_id, confidence, matcher, warnings, compatibility, requirements, and optional factual source metadata. It does not execute the workflow.

Dify compiler and internal execution

Method	Path	Behavior
`POST`	`/v1/dify/analyze`	static suggestions only
`POST`	`/v1/dify/compile`	returns Python source for target `ragspine` or `spineagent`; no execution
`POST`	`/v1/dify/run`	compile, gate, and execute only when enabled
`POST`	`/v1/dify/run/jobs`	synchronously compile/gate, then enqueue when enabled

Analyze, compile, and run accept exactly one document form:

{ "workflow": { "app": { "mode": "workflow" }, "workflow": { "graph": {} } } }

or the legacy envelope:

{ "yaml": "app:\n  mode: workflow\nworkflow:\n  graph: {}\n" }

Unknown fields and providing both/neither forms are rejected. RAGSPINE_DIFY_RUN_ENABLED defaults to false, producing 403 for execution. Providers are built from server configuration only.

n8n conversion and internal execution

Method	Path	Behavior
`POST`	`/v1/n8n/convert`	pure `n8n_to_dify` or `dify_to_n8n` conversion with warnings
`POST`	`/v1/n8n/run`	convert then reuse the default-off Dify run path

Conversion accepts a mapping (or a JSON/YAML string in the conversion envelope) and never runs it.

Dify-compatible public Workflow API

All four routes require Authorization: Bearer <app-key>. App keys and server-side workflow paths are registered in RAGSPINE_DIFY_PUBLIC_APPS; an absent registry returns 401.

Method	Path
`POST`	`/v1/workflows/run`
`GET`	`/v1/workflows/run/{workflow_run_id}`
`GET`	`/v1/info`
`GET`	`/v1/parameters`

A run request requires user, accepts inputs, and selects response_mode as blocking or streaming. The key selects the server-side workflow; clients do not upload a workflow or provider. Execution still requires RAGSPINE_DIFY_RUN_ENABLED=true.

n8n-compatible public API

Every /api/v1/* route requires X-N8N-API-KEY matching RAGSPINE_N8N_API_KEY. If the server key is unset, the surface is disabled with 401.

Method	Path
`GET`, `POST`	`/api/v1/workflows`
`GET`, `PUT`, `DELETE`	`/api/v1/workflows/{workflow_id}`
`POST`	`/api/v1/workflows/{workflow_id}/activate`
`POST`	`/api/v1/workflows/{workflow_id}/deactivate`
`GET`	`/api/v1/executions`
`GET`, `DELETE`	`/api/v1/executions/{execution_id}`
`GET`, `POST`	`/webhook/{path}`

Collection pagination uses limit (default 100, accepted/clamped to 1–250) and cursors. Webhooks are the exception to API-key authentication: they intentionally accept unauthenticated GET/POST, match active workflows only, and remain behind the default-off execution flag.

Limits, errors, and deployment security

The scaffold and selected Dify POST routes reject bodies larger than 2 MiB before buffering; a decoded workflow document is limited to 1 MiB and has additional depth/node/string/YAML-alias limits. Validation responses remove echoed input/context. Internal failures return opaque error objects and no traceback.

There is no built-in authentication for engine, catalog, compiler, converter, topology, or internal run routes. Public deployments must add network isolation or a reverse proxy. The webhook route needs ingress authentication/rate limiting if its URL secrecy is insufficient.