HTTP API Reference

pg_ripple_http is a standalone Rust binary that exposes the full pg_ripple feature set over HTTP. It supports the W3C SPARQL 1.1 Protocol, Server-Sent Events streaming, Datalog REST operations, PageRank, probabilistic reasoning, Arrow Flight bulk export, and administrative endpoints.

Start the service:

PG_RIPPLE_HTTP_PG_URL=postgresql://localhost/mydb \
PG_RIPPLE_HTTP_PORT=7878 \
PG_RIPPLE_HTTP_AUTH_TOKEN=mysecret \
pg_ripple_http

Authentication

All endpoints that mutate state require a Bearer token when PG_RIPPLE_HTTP_AUTH_TOKEN is set.

Authorization: Bearer <token>

Read-only endpoints (GET /health, GET /metrics, GET /openapi.yaml) do not require authentication.

Configuration

Complete Endpoint Reference

Read and Write mean the endpoint calls the HTTP companion's read or write authentication check when PG_RIPPLE_HTTP_AUTH_TOKEN is configured. None means the endpoint is intentionally unauthenticated.

SPARQL Endpoints

GET /sparql

W3C SPARQL 1.1 Protocol query endpoint.

Query Parameters:

Accept header controls the result format:

Example:

curl -G "http://localhost:7878/sparql" \
  --data-urlencode 'query=SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10' \
  -H "Accept: application/sparql-results+json"

POST /sparql

Accepts the query either as an application/x-www-form-urlencoded body (form post) or as a raw application/sparql-query / application/sparql-update body.

Form body parameters: same as GET /sparql query parameters.

Example (SELECT):

curl -X POST http://localhost:7878/sparql \
  -H "Content-Type: application/sparql-query" \
  -d 'SELECT ?label WHERE { <https://example.org/Alice> rdfs:label ?label }'

Example (UPDATE, requires auth):

curl -X POST http://localhost:7878/sparql \
  -H "Content-Type: application/sparql-update" \
  -H "Authorization: Bearer $TOKEN" \
  -d 'INSERT DATA { <:Alice> rdfs:label "Alice" }'

POST /sparql/stream

Streaming SPARQL SELECT using Server-Sent Events. Results are delivered as SSE data: events, one result row per event, as the query executes.

Request: Same as POST /sparql.

Response Content-Type: text/event-stream

Event format:

event: row
data: {"?name": "\"Alice\"^^xsd:string", "?age": "\"30\"^^xsd:integer"}

event: done
data: {"total_rows": 42}

Example:

curl -X POST http://localhost:7878/sparql/stream \
  -H "Content-Type: application/sparql-query" \
  -H "Accept: text/event-stream" \
  -d 'SELECT ?s ?p ?o WHERE { ?s ?p ?o }' \
  --no-buffer

RAG Endpoint

POST /rag

Execute a hybrid SPARQL + vector-similarity RAG retrieval query. The endpoint embeds the question, finds the nearest RDF entities by cosine similarity, and returns structured results with a plain-text context string suitable for use as an LLM prompt.

Content-Type: application/json

Request body:

{
  "question": "what treats headaches?",
  "sparql_filter": "?entity a <https://pharma.example/Drug>",
  "k": 5,
  "model": "text-embedding-3-small",
  "output_format": "jsonb"
}

Response (200 OK):

{
  "results": [
    {
      "entity_iri": "https://pharma.example/aspirin",
      "label": "aspirin",
      "context_json": {
        "label": "aspirin",
        "types": ["Drug", "NSAID"],
        "properties": [{"predicate": "treats", "object": "headache"}],
        "contextText": "aspirin. Type: NSAID, Drug."
      },
      "distance": 0.12
    }
  ],
  "context": "aspirin. Type: NSAID, Drug.\n\nibuprofen. Type: Drug."
}

The context field is a concatenated plain-text summary ready for use as an LLM system prompt.

JSON Mapping Writeback

POST /json-mapping/{name}/writeback

Synchronously write one RDF subject back to the relational table configured for the named JSON mapping. This calls pg_ripple.writeback_json_row(name, subject_iri) and requires write auth when authentication is enabled.

Content-Type: application/json

{
  "subject_iri": "https://example.com/contacts/c001"
}

Response (200 OK):

{
  "rows_affected": 1
}

Error mapping:

GET /json-mapping/{name}/writeback/status

Return queue depth, error count, and last processed timestamp for one mapping. This is a filtered HTTP view over pg_ripple.json_writeback_status() and requires read auth when authentication is enabled.

Response (200 OK):

{
  "mapping_name": "contacts",
  "pending": 0,
  "errors": 0,
  "last_error": null,
  "last_processed_at": null
}

Arrow Flight Bulk Export

POST /flight/do_get

Bulk-export SPARQL query results as an Apache Arrow IPC record stream. Suitable for high-throughput extract pipelines (DuckDB, pandas, Spark).

Content-Type: application/json

Request body:

{
  "ticket": "eyJhbGciOiJIUzI1NiJ9...",
  "query": "SELECT ?s ?p ?o WHERE { ?s ?p ?o }"
}

Response: application/vnd.apache.arrow.stream — Arrow IPC stream.

Example (Python):

import requests, pyarrow as pa

# 1. Get a signed ticket from PostgreSQL
ticket = pg.execute("SELECT pg_ripple.arrow_flight_ticket('SELECT ?s ?p ?o WHERE { ?s ?p ?o }')")

# 2. Stream the Arrow IPC export
r = requests.post("http://localhost:7878/flight/do_get",
    json={"ticket": ticket},
    headers={"Authorization": f"Bearer {token}"},
    stream=True)

reader = pa.ipc.open_stream(r.raw)
table = reader.read_all()
print(table.to_pandas())

Streaming Subscriptions

GET /subscribe/{subscription_id}

Subscribe to a live SPARQL result stream via Server-Sent Events. The subscription_id is returned by pg_ripple.subscribe(query).

Response Content-Type: text/event-stream

Event types:

Example:

# Create subscription in PostgreSQL
psql -c "SELECT pg_ripple.subscribe('SELECT ?s ?p ?o WHERE { ?s ?p ?o }')"
-- Returns: sub_abc123

# Connect SSE stream
curl -N "http://localhost:7878/subscribe/sub_abc123" \
  -H "Accept: text/event-stream"

Datalog REST API

GET /datalog/rules

List all registered Datalog rule sets.

Response (200 OK):

[
  {"rule_set": "rdfs_closure", "rule_count": 13, "enabled": true},
  {"rule_set": "custom_rules", "rule_count": 5, "enabled": true}
]

POST /datalog/rules/{rule_set}/add

Add a Datalog rule to a rule set.

Content-Type: application/json

{
  "rule": "ancestor(?x, ?z) :- ancestor(?x, ?y), parent(?y, ?z).",
  "enabled": true
}

Response (200 OK):

{"rule_id": "rule_42", "rule_set": "custom_rules"}

POST /datalog/infer/{rule_set}

Run forward-chaining inference for a rule set.

Content-Type: application/json

{
  "graph": "https://example.org/graph1",
  "max_iterations": 100,
  "dry_run": false
}

Response (200 OK):

{
  "derived_count": 847,
  "iterations": 3,
  "elapsed_ms": 42,
  "stratification_order": ["base_rules", "closure_rules"]
}

POST /datalog/infer/{rule_set}/wfs

Run well-founded semantics inference. Returns three-valued results (true / false / undefined) for recursive rules with negation.

POST /datalog/infer/{rule_set}/demand

Goal-directed magic-sets inference. Only derives facts relevant to a specific query goal.

Content-Type: application/json

{
  "goal": "ancestor(<:Alice>, ?z)",
  "graph": "https://example.org/graph1"
}

POST /datalog/query/{rule_set}

Run a single Datalog goal query against a materialized rule set without modifying the store.

Content-Type: application/json

{
  "goal": "ancestor(<:Alice>, ?z)",
  "limit": 100
}

Response (200 OK):

{
  "results": [
    {"?z": "<https://example.org/Bob>"},
    {"?z": "<https://example.org/Carol>"}
  ],
  "total": 2
}

GET /datalog/constraints

Check all constraint rules across all rule sets.

Response (200 OK):

{
  "violations": [
    {
      "rule_set": "integrity_rules",
      "constraint": "uniqueness_violation",
      "violating_bindings": [{"?x": "<:entity1>"}]
    }
  ],
  "total_violations": 1
}

GET /datalog/stats/cache

Returns rule plan cache hit/miss statistics.

GET /datalog/stats/tabling

Returns tabling cache occupancy and eviction statistics.

PageRank API

POST /pagerank/run

Start a PageRank computation job.

Content-Type: application/json

{
  "graph": "https://example.org/graph1",
  "edge_predicates": ["schema:knows", "schema:worksFor"],
  "damping": 0.85,
  "max_iterations": 100,
  "convergence_delta": 0.0001
}

Response (200 OK):

{
  "job_id": "pr_20250503_001",
  "status": "running",
  "started_at": "2025-05-03T12:00:00Z"
}

GET /pagerank/status

Poll the status of the most recent PageRank job.

Response:

{
  "job_id": "pr_20250503_001",
  "status": "completed",
  "iterations": 47,
  "elapsed_ms": 1204,
  "node_count": 50000,
  "edge_count": 250000
}

GET /pagerank/export

Export PageRank scores as JSON or CSV.

Query parameters:

Response (200 OK, JSON):

{
  "scores": [
    {"iri": "https://example.org/Alice", "score": 0.0423, "rank": 1},
    {"iri": "https://example.org/Bob", "score": 0.0381, "rank": 2}
  ],
  "total": 50000
}

GET /pagerank/explain/{node_iri}

Explain the PageRank score for a specific node, showing top contributing in-edges.

Path parameter: node_iri — URL-encoded IRI.

Response:

{
  "iri": "https://example.org/Alice",
  "score": 0.0423,
  "rank": 1,
  "top_contributors": [
    {"from_iri": "https://example.org/Bob", "edge_weight": 0.012},
    {"from_iri": "https://example.org/Carol", "edge_weight": 0.009}
  ]
}

POST /centrality/run

Compute centrality metrics (degree, betweenness, Katz).

Content-Type: application/json

{
  "graph": "https://example.org/graph1",
  "metrics": ["degree", "katz"],
  "katz_alpha": 0.01
}

POST /pagerank/find-duplicates

Find near-duplicate nodes by PageRank score similarity and graph structure.

Confidence / Probabilistic API

POST /confidence/load

Load triples with associated confidence scores.

Content-Type: application/json

{
  "triples": [
    {
      "subject": "https://example.org/Alice",
      "predicate": "rdf:type",
      "object": "schema:Person",
      "confidence": 0.95,
      "graph": "https://example.org/g1"
    }
  ]
}

Response (200 OK):

{"inserted": 1, "updated": 0}

GET /confidence/shacl-score

Get SHACL soft-validation confidence scores for shapes.

Query parameters:

GET /confidence/shacl-report

Get a full SHACL validation report with confidence scores per constraint.

POST /confidence/vacuum

Vacuum stale confidence score rows from _pg_ripple.confidence.

Administrative Endpoints

GET /health

Returns {"status": "ok"} when the service is running and the database connection pool is healthy.

Response: 200 OK — {"status": "ok"} Response: 503 Service Unavailable — database unreachable.

GET /health/ready

Kubernetes-compatible readiness probe. Checks that the PostgreSQL connection pool has at least one available connection.

GET /metrics

Prometheus-format metrics. No authentication required.

Key metrics:

GET /metrics/extension

Extension-internal Prometheus metrics sourced directly from the pg_ripple extension within PostgreSQL.

GET /void

Returns a VoID (Vocabulary of Interlinked Datasets) dataset description, summarizing the RDF store contents: triple counts, predicate frequencies, and class distributions.

Accept: text/turtle or application/ld+json

GET /service

Returns a SPARQL 1.1 Service Description document describing the endpoint's capabilities.

Accept: text/turtle or application/ld+json

GET /openapi.yaml

Returns the full OpenAPI 3.1 specification for the pg_ripple_http API.

GET /explorer

Web-based SPARQL explorer UI — an embedded query editor with syntax highlighting, result table, and endpoint configuration.

Error Responses

All error responses use a consistent JSON envelope:

{
  "error": "PT440",
  "message": "query exceeds maximum algebra depth (256)",
  "hint": "Simplify the query or raise pg_ripple.sparql_max_algebra_depth"
}

Security

• Bearer token authentication controls mutating endpoints
• SSRF protection: federation SERVICE endpoints are checked against federation_endpoint_policy
• SQL injection prevention: all queries use parameterized PostgreSQL SPI
• Arrow Flight tickets are HMAC-SHA256 signed; set pg_ripple.arrow_flight_secret
• Rate limiting: per-IP, configurable via PG_RIPPLE_HTTP_RATE_LIMIT
• HTTPS termination should be handled by a reverse proxy (nginx, Caddy, Traefik)
• Never expose PG_RIPPLE_HTTP_AUTH_TOKEN in URLs or logs