Agent API

Any program that can make HTTP calls can use a Spark Memory. Every agent connects with its own key, under a grant the memory's owner controls, and every access is recorded. This page is the reference. If you are connecting Claude Code, Codex, OpenCode, or another MCP tool, the Sharing page in the app gives you the exact command, and you do not need anything here.

Addresses and keys#

Your memory's address is the one in your browser when you open it, in the form https://ai.solderspark.com/m/<memory-id>. Every call below is made against that address.

Agent keys are created on the Access and trust page. Each key belongs to one named agent and carries a grant that says, per room, whether the agent is answered at once, must wait for approval, or is refused. Send the key as a bearer token.

Authorization: Bearer YOUR-AGENT-KEY

Keys can be rotated or removed at any time from the same page. A removed key stops working at once.

Ask a question#

# One room
curl -X POST "https://ai.solderspark.com/m/<memory-id>/api/agent/ask?region=sales&q=Who%20owns%20billing" \
  -H "Authorization: Bearer YOUR-AGENT-KEY"

# Every room the grant allows
curl -X POST "https://ai.solderspark.com/m/<memory-id>/api/agent/ask?scope=super&q=Who%20owns%20billing" \
  -H "Authorization: Bearer YOUR-AGENT-KEY"

# As it stood on a date
curl -X POST "https://ai.solderspark.com/m/<memory-id>/api/agent/ask?region=sales&q=What%20was%20the%20budget&as_of=2026-03-03" \
  -H "Authorization: Bearer YOUR-AGENT-KEY"

A question that is allowed comes back answered.

{
  "status": "answered",
  "agent": "deal-desk",
  "regions_searched": ["sales"],
  "question": "Who owns billing",
  "answer": "Anna Berg owns billing, since March 2026.",
  "beliefs": [
    {
      "id": "b_9f2c",
      "region": "sales",
      "claim": "Billing is owned by Anna Berg",
      "observed": "2026-03-04",
      "history": "Billing was owned by Tom Reyes (2025-01-10 to 2026-03-04)",
      "flags": [],
      "score": 0.91
    }
  ]
}

The beliefs list is the answer. Each row is one fact with where it came from, when it was observed, what it replaced, and any warning flags. The answer sentence is composed from those rows for convenience. Build your agent's statements on the rows and cite their ids, and say what is missing rather than filling gaps from general knowledge.

as_of reads the facts that were current on that date. Facts that changed since are shown as they stood then, and the answer says so.

When a person has to approve#

If the room needs approval, the reply is 202 with a request id.

{ "status": "pending", "request_id": "r_41ab", "message": "a person must approve this question for region \"sales\"" }

The memory's owner sees the question in their Review queue and decides. Poll for the outcome with the id. A held question is kept until it is decided, and an agent can only read the results of its own requests.

curl "https://ai.solderspark.com/m/<memory-id>/api/agent/result?id=r_41ab" \
  -H "Authorization: Bearer YOUR-AGENT-KEY"

A refused question returns 403 with "status": "denied", and the refusal is recorded too.

Warning flags#

A row may carry flags. Respect them.

Feed knowledge in#

Feeds post to a memory with a feed key, created on the Sources page. Each feed has a name, a trust level, and the rooms it may write to. Nothing inside a message can raise its own trust level.

curl -X POST "https://ai.solderspark.com/m/<memory-id>/api/connect/webhook" \
  -H "Content-Type: application/json" \
  -H "X-Connector-Key: YOUR-FEED-KEY" \
  -d '{"content": "Cert rotation on the API gateway completed.", "author": "ci-bot", "observed_at": "2026-08-29T18:40:00Z"}'

Always send observed_at, the time the thing was observed or became true. Facts are dated by it, and answers say how old each fact is, so a migrated fact stamped with today's date would quietly pretend to be current. When moving old data across, carry the original timestamps.

The reply is a receipt saying what the memory picked up, whether it was kept or dropped as noise, and which facts were written. Ready made connections for mail, chat, and documents are covered in Integrations.

MCP#

Spark Memory speaks MCP, so any framework that supports the Model Context Protocol can connect directly. Point it at https://ai.solderspark.com/m/<memory-id>/mcp with the agent's key as a bearer token. The same grants, approvals, and audit records apply.

Connections are read only unless the memory's owner marks them as able to add knowledge on the Sharing page. Only then does remember appear. Everything it writes is recorded under the connection's own name, lands only in rooms it can read, and can never outrank what the owner recorded directly.

Open loops#

A memory tracks commitments, requests, and decisions that are still waiting for an outcome, each with an owner and a due date when one was stated. GET /api/loops lists them and POST /api/loops/close marks one done. Loops also close on their own when a later message or fact shows the outcome happened.

The rulebook#

GET /api/standards on your memory returns its rulebook, which covers its rooms, how facts are named and typed, and how sources are ranked. Put it in your agent's system prompt so that what it writes can be found and what it reads makes sense.

Errors and limits#

Ask short, specific questions, a system name, a person, a topic, rather than one long essay. Stay inside one room unless the task truly needs more, because every cross room question is logged.