#HTTP API

WWKG exposes a standards-based HTTP API for SPARQL queries, graph management, and administration. The server listens on port 4242 by default.

#SPARQL Protocol endpoint

#Query

POST /sparql
Content-Type: application/sparql-query

SELECT ?s ?p ?o WHERE { ?s ?p ?o } LIMIT 10

Or with URL-encoded form data:

POST /sparql
Content-Type: application/x-www-form-urlencoded

query=SELECT+%3Fs+%3Fp+%3Fo+WHERE+%7B+%3Fs+%3Fp+%3Fo+%7D+LIMIT+10

#Update

POST /sparql
Content-Type: application/sparql-update

INSERT DATA { <http://example.org/Alice> <http://example.org/age> 31 . }

#Explain

POST /sparql?explain=true
Content-Type: application/sparql-query

SELECT ?name WHERE { ?person <http://example.org/name> ?name . }

Returns the query execution plan without running the query.

#Graph Store Protocol

The Graph Store Protocol (GSP) provides RESTful access to named graphs.

#Retrieve a graph

GET /graph-store?graph=urn:wwkg:graph:people
Accept: application/n-triples

#Replace a graph

PUT /graph-store?graph=urn:wwkg:graph:people
Content-Type: text/turtle

@prefix : <http://example.org/> .
:Alice :name "Alice" .
:Bob   :name "Bob" .

#Append to a graph

POST /graph-store?graph=urn:wwkg:graph:people
Content-Type: text/turtle

@prefix : <http://example.org/> .
:Carol :name "Carol" .

#Delete a graph

DELETE /graph-store?graph=urn:wwkg:graph:people

#Default graph

Use ?default to target the default graph:

GET /graph-store?default

GSP selector rules:

• Triple payloads (N-Triples, Turtle, RDF/XML): exactly one of ?default or ?graph=<iri> is required.
• Quad payloads (N-Quads, TriG; planned): ?default and ?graph= are rejected; graph context comes from the payload.

Graph IRI policy:

• User graph IDs may use any valid IRI scheme (urn:, http:, https:, file:, …).
• urn:wwkg:graph:default is reserved for the virtual default graph and cannot be used as a named graph ID.

#Content negotiation

#Request formats (Content-Type)

#Response formats (Accept)

#Authentication

WWKG supports two caller-authentication mechanisms for privileged routes.

#API token

For scripts and automation, send your API token in the x-wwkg-api-key header:

x-wwkg-api-key: <api-token>

This resolves a caller identity via the server’s token index (sys:auth).

#Browser session (Clerk JWT)

For the web interface (and any JWT-based integration), send:

Authorization: Bearer <jwt>

The JWT must be verifiable by the node’s configured JWKS issuer and include the WWKG DID claim expected by server authorization.

For WWKG website integrations:

• token retrieval uses Clerk template token (wwkg by default)
• server must have CLERK_JWKS_URL configured, including in local development

Without a valid JWT or API token, privileged endpoints return 401.

#Branch and workspace selection

#URL parameters

POST /sparql?branch=experiment
POST /sparql?workspace=urn:wwkg:workspace:550e8400-e29b-41d4-a716-446655440000

#Request headers

X-WWKG-Branch: experiment
X-WWKG-Workspace: urn:wwkg:workspace:550e8400-e29b-41d4-a716-446655440000
X-WWKG-Commit: bafyrei...abc
X-WWKG-AsOf: 2025-02-10T14:30:00Z

When both a header and URL parameter are present, the header takes precedence.

#Response headers

Every query response includes version metadata: