> ## Documentation Index
> Fetch the complete documentation index at: https://artemiscity.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Working with ATP messages

> A task-oriented walkthrough for building, exchanging, and inspecting Agent Transmission Protocol (ATP) messages — companion to the full tag and endpoint reference.

This page is a walkthrough, not the reference. For the complete tag specification,
`ActionType` catalog, and every ATP REST endpoint, see [Agent Transmission Protocol
(ATP)](/api/api-reference#agent-transmission-protocol-atp) in the API reference. Use this page
to go from "I have data to send" to a validated, routable message.

<Tabs>
  <Tab title="Builder">
    Every ATP message is six header tags followed by a JSON body. Fill them in this order:

    <Steps>
      <Step title="Mode">
        How the message should be delivered: `direct`, `batch`, `stream`, or `async`. Most
        agent-to-agent calls are `direct`.
      </Step>

      <Step title="Context">
        A trace/correlation ID, unique per logical operation (max 64 chars). Reuse the same
        `Context` across a request/response pair so the two sides of an exchange can be
        joined in logs and in `GET /api/v1/atp/queue`.
      </Step>

      <Step title="Priority">
        `critical` (0), `high` (1), `normal` (2), or `low` (3) — determines queue order, not
        correctness. Reserve `critical` for governance overrides and rollbacks.
      </Step>

      <Step title="ActionType">
        What the receiving agent should do with the payload — `query`, `execute`,
        `propose_update`, and so on. See the full catalog grouped by Query / Modification /
        Execution / Management / Governance operations in the
        [ATP reference](/api/api-reference#actiontype-values).
      </Step>

      <Step title="TargetZone">
        Which system component owns this: `kernel`, `registry`, `memory`, `sandbox`, or
        `governance`. This is what the router matches on.
      </Step>

      <Step title="SpecialNotes (optional)">
        Free-text hints for the receiving agent, max 256 chars — for example
        `retry on timeout` or `require_semantic_match=true`.
      </Step>
    </Steps>

    Assembled, a memory lookup looks like this:

    ```text theme={null}
    #Mode direct
    #Context task-exec-2026-07-01-abc123
    #Priority high
    #ActionType query
    #TargetZone memory
    #SpecialNotes require_semantic_match=true

    {
      "query_type": "semantic",
      "text": "Find tasks related to data processing",
      "top_k": 5
    }
    ```

    Before sending, run it through `POST /api/v1/atp/validate` — it checks structural and
    field-level errors without dispatching anything, so it's safe to call from client-side
    forms or CI. `POST /api/v1/atp/format` returns the exact wire string for a payload if
    you want to confirm formatting before it ships.
  </Tab>

  <Tab title="Example exchange">
    A minimal request → route → respond cycle, using the same `Context` end to end so the
    three calls are easy to correlate in logs.

    **1. Submit the task** — `POST /api/v1/atp/send`

    ```json theme={null}
    {
      "header": {
        "mode": "direct",
        "context": "exec-2026-07-01-abc",
        "priority": "high",
        "actionType": "execute",
        "targetZone": "kernel",
        "senderId": "agent-uuid"
      },
      "payload": {
        "content": "Analyze the following document..."
      }
    }
    ```

    ```json theme={null}
    { "success": true, "messageId": "9c1e...uuid" }
    ```

    **2. Preview the routing decision** — `POST /api/v1/atp/route` (optional; useful when
    debugging why a message went where it did)

    ```json theme={null}
    {
      "success": true,
      "data": {
        "targetAgents": ["agent-uuid"],
        "rationale": "Matched on actionType=execute and targetZone=kernel"
      }
    }
    ```

    **3. Fetch the result** — `GET /api/v1/atp/response/9c1e...uuid` once the target agent
    has finished. If nothing has responded yet, `GET /api/v1/atp/queue` shows whether the
    message is still waiting and at what priority depth.
  </Tab>

  <Tab title="Playground">
    ATP's endpoints aren't in `api/openapi.yaml` yet, so they don't have a live "Try it"
    widget on this site — the calls below are copy-pasteable `curl`.

    ```bash theme={null}
    # Validate before sending
    curl -X POST https://api.artemiscity.com/api/v1/atp/validate \
      -H "Authorization: Bearer $ARTEMIS_API_KEY" \
      -H "Content-Type: application/json" \
      -d @message.json

    # Send
    curl -X POST https://api.artemiscity.com/api/v1/atp/send \
      -H "Authorization: Bearer $ARTEMIS_API_KEY" \
      -H "Content-Type: application/json" \
      -d @message.json

    # Check the queue
    curl https://api.artemiscity.com/api/v1/atp/queue \
      -H "Authorization: Bearer $ARTEMIS_API_KEY"
    ```

    Need the allowed values for any header field while building a form or CI check? They're
    all queryable: `GET /api/v1/atp/modes`, `GET /api/v1/atp/priorities`,
    `GET /api/v1/atp/action-types`, and `GET /api/v1/atp/template` for a fully annotated
    starter message.

    <Warning>
      All ATP endpoints require authentication. A message that fails
      `POST /api/v1/atp/validate` will also be rejected by `/send` — validate first in any
      automated pipeline rather than handling the send-time error.
    </Warning>
  </Tab>
</Tabs>

## Related

* [Agent Transmission Protocol reference](/api/api-reference#agent-transmission-protocol-atp) — full tag spec, `ActionType` catalog, and every ATP REST endpoint
* [Trust scoring and access levels](/Documentation/governance/trust-scoring) — how `senderId` trust affects which `ActionType` values an agent is actually allowed to issue
* [Multi-agent communication](/Documentation/architecture/routing-modes) — how `TargetZone` and routing modes interact


## Related topics

- [API Reference](/api/api-reference.md)
- [Artemiscity (Hebbian Agents) Whitepaper V.3](/Documentation/concepts/whitepaper.md)
- [Changelog](/Changelog/changelog.md)
- [LIVING_CITY](/Documentation/Introduction/LIVING_CITY.md)
- [Kernel CLI](/Documentation/architecture/kernel-cli.md)