Common integration patterns

These application-owned patterns apply across Agent API resource groups. They do not substitute for an operation’s deployed authentication, idempotency, error, or event contract.

Keep authentication at the edge

Create a small API client that owns the Neuron base URL, signing material, JWT, and refresh policy. Business code should ask it to perform an operation rather than passing tokens throughout the application.

async function postNeuron(path, body) {
  const jwt = await tokenManager.validToken();
  const response = await fetch(new URL(path, neuronBase), {
    method: "POST",
    headers: {
      Authorization: `Bearer ${jwt}`,
      "Content-Type": "application/json",
      Accept: "application/json"
    },
    body: JSON.stringify(body)
  });

  if (!response.ok) throw await NeuronError.from(response);
  return response.json();
}

Add refresh only after its deployed lifecycle has been verified. Bound it to one attempt so an invalid credential or disabled account cannot create an authentication loop.

Separate command and retrieval paths

Treat operations such as signing, sending a message, transferring value, or changing a contract as commands. Do not automatically retry them unless the endpoint has an idempotency mechanism or you can prove from the returned identifier that the command did not run. Queries and reads may be safer to repeat, but the platform-wide transient status set and Retry-After behavior are not currently specified. Retry only conditions verified for the deployment, with a bounded attempt count and jitter.

Poll incrementally

Use pagination only where the operation schema actually defines a bound, cursor, offset, or continuation value. For message retrieval, process a returned batch transactionally before invoking a separate destructive clear operation.

Preserve domain boundaries

An Agent account and its JWT belong to one Neuron. Keep a separate client/session per host. Before multi-Neuron actions:

identify which host owns the account or object;
use federation, XMPP, or Remote Quick Login for cross-domain interaction;
never replay a host-bound signature or bearer token against another domain;
do not assume a local operation can read or modify a foreign object unless its operation description explicitly documents federation.

Decode structured failures

Branch first on HTTP status, then parse the response body only when its schema is known. Log a local correlation ID, operation, host, and status—but never credentials, JWTs, legal documents, raw contract attachments, or personal identifiers. See Error handling.

Make event processing idempotent

XMPP, browser events, queues, and external services can redeliver work. Persist a stable message, contract, token, or business-operation ID before applying side effects. A duplicate should return the previously committed result.

Start with the Agent API

Agent API basics

Reliability and security

Resources

Endpoints

Keep authentication at the edge

Separate command and retrieval paths

Poll incrementally

Preserve domain boundaries

Decode structured failures

Make event processing idempotent

​Keep authentication at the edge

​Separate command and retrieval paths

​Poll incrementally

​Preserve domain boundaries

​Decode structured failures

​Make event processing idempotent

Keep authentication at the edge

Separate command and retrieval paths

Poll incrementally

Preserve domain boundaries

Decode structured failures

Make event processing idempotent