> For the complete documentation index, see [llms.txt](https://docs.origintrail.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.origintrail.io/build-with-dkg/http-application.md).

# 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](https://docs.origintrail.io/operate/publish-and-query.md).

## Connection and credentials

Start a node and create a Context Graph as in the [quickstart](https://docs.origintrail.io/start-here/quickstart.md). 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):

```bash
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:

```bash
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`](https://github.com/OriginTrail/dkg/blob/main/examples/docs/http-app.mjs) and [`atlas-query.rq`](https://github.com/OriginTrail/dkg/blob/main/examples/docs/atlas-query.rq) from the same reviewed repository revision and save them together. From that directory:

```bash
node http-app.mjs write
node http-app.mjs read
```

`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:

```bash
node http-app.mjs share
node http-app.mjs read shared-working-memory
```

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](https://docs.origintrail.io/references/node-skill.md) 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](https://docs.origintrail.io/operate/large-content.md) |
| `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](https://docs.origintrail.io/operate/async-publisher-wallets.md); 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](https://docs.origintrail.io/build-with-dkg/async-jobs.md).

## 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.origintrail.io/build-with-dkg/http-application.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
