Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Integrate an HTTP Application

Connect your application to knowledge that agents and other systems can use. For example, a product service can contribute component relationships while a research tool retrieves the evidence behind a finding. The node's authenticated HTTP API gives your application access to graph queries and the knowledge lifecycle.

This example starts with the same small Atlas record as the quickstart: create a draft, read its relationships and source, and optionally share it. It uses Node.js 22.13+ and the built-in fetch, with no monorepo dependencies. On-chain publication is covered in the separate publish guide.

Connection and credentials

Start a node and create a Context Graph as in the quickstart. Copy its exact ID. On the node host, a local operator can discover the local token with dkg auth show. For a remote application, the operator registers an agent and provisions its returned authToken through the application's secret store. Keep the node-admin token on its owner host.

Set these environment variables in the application's environment (do not commit their values):

export DKG_NODE_URL='http://127.0.0.1:9200'
export DKG_CONTEXT_GRAPH='<exact existing Context Graph ID>'
export DKG_KA_NAME='atlas-app'
# Local operator demonstration only:
export DKG_AUTH_TOKEN="$(dkg auth show | head -n 1)"

This selects the first local configured token. Confirm the caller before writing:

curl --fail --silent --show-error \
  -H "Authorization: Bearer $DKG_AUTH_TOKEN" \
  "$DKG_NODE_URL/api/agent/identity"

Check that the returned agentAddress is the intended author. A remote application's own agent token can resolve to a different identity from the node operator.

For remote access, use an operator-configured HTTPS endpoint. Opening a public port is not an authentication strategy. Agent credentials and the application's own end-user authorization are separate: decide which graphs and records each user may access before forwarding requests.

Run the supplied client

Get http-app.mjs and atlas-query.rq from the same reviewed repository revision and save them together. From that directory:

write creates the named draft and appends the five sample triples. read queries the requested Context Graph's Working Memory. Expect a bindings result containing Atlas, Oxigraph, and https://example.org/dkg-tutorial/source. Rerun read in a new process to demonstrate that the data is in the node. The example prints returned evidence, not a model-generated answer.

For an intentional share of this public sample:

The client checks HTTP errors and partial 207 results, uses a bounded request timeout, and never retries a mutation automatically. A share succeeds only when the response confirms swmShared: true; an error-free HTTP 200 alone does not establish completion. A committed replay can succeed with zero newly promoted triples. It is a minimal example, not a background ingestion service.

share calls the node's seal-before-share route directly. If a response is lost or bookkeeping fails after the share commits, inspect the existing KA, then rerun share with the same Context Graph ID and KA name. The route can resume the existing share even after WM is empty. Do not rerun write or finalize an empty draft as a prerequisite for that recovery.

The request contract

All JSON writes send Content-Type: application/json and a bearer token.

Operation
Method and route
Body or query
Evidence to inspect

Caller identity

GET /api/agent/identity

None

agentAddress and the expected caller

Create WM draft

POST /api/knowledge-assets

{ "contextGraphId": "<id>", "name": "atlas-app" }

Named assertion/KA and status

Write

POST /api/knowledge-assets/atlas-app/wm/write

{ "contextGraphId": "<id>", "quads": [...] }

Written count; inspect contents

Read graph

POST /api/query

{ "contextGraphId": "<id>", "view": "working-memory", "sparql": "..." }

result.type and result.bindings

Seal

POST /api/knowledge-assets/atlas-app/wm/finalize

{ "contextGraphId": "<id>" }

Seal metadata and author

Share

POST /api/knowledge-assets/atlas-app/swm/share

{ "contextGraphId": "<id>", "entities": "all" }

swmShared: true without nested errors

A quad is { "subject": "<IRI>", "predicate": "<IRI>", "object": "<IRI or RDF literal>" }. For a string literal the object includes RDF quotes, for example "object": "\"Atlas\"". The node controls WM graph placement; do not invent per-quad graph routing. Query views are working-memory, shared-working-memory, and verifiable-memory; specify the exact Context Graph with the view.

The Node Skill is the complete operational reference. Match it to the running version and use discovered MCP schemas when calling tools instead of HTTP.

Handle incomplete operations

Result
Application behavior

400

Correct the payload/identifier; repeating it will not fix it

401 / 403

Resolve credentials or permissions; do not broaden access automatically

404

Check the exact graph/KA/route and installed version

409

Inspect the conflict or existing job; do not create a replacement KA to bypass it

207 or nonempty errors

Inspect partial effects before proceeding

413

Reduce the payload using large-content guidance

429 / retryable 503

Follow the operation's backoff/recovery contract; preserve its identity

Network timeout

Outcome may be unknown; inspect the KA or job before repeating a mutation

For async sharing, store the returned job ID and poll /api/knowledge-assets/swm/share-jobs/{jobId}. queued, running, and failed_retrying are not success; completion requires succeeded. Inspect terminal failures before recovery. For publication, use the distinct publisher job contract; its states and transaction recovery are not the share queue's states. What each async response means, and how to retry or recover safely, is in Async Share and Publish Jobs.

Extend the example

Assign stable source/entity identifiers, record provenance, and keep a durable import manifest for resumable ingestion. Treat retries, schema migrations, updates, deletion, and per-user access as application requirements. Validate returned evidence before allowing an agent to act on it.

Last updated

Was this helpful?