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) in the API reference. Use this page to go from “I have data to send” to a validated, routable message.

Builder

Every ATP message is six header tags followed by a JSON body. Fill them in this order:

1. Mode

   How the message should be delivered: direct, batch, stream, or async. Most agent-to-agent calls are direct.

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

3. Priority

   critical (0), high (1), normal (2), or low (3) — determines queue order, not correctness. Reserve critical for governance overrides and rollbacks.

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

5. TargetZone

   Which system component owns this: kernel, registry, memory, sandbox, or governance. This is what the router matches on.

6. SpecialNotes (optional)

   Free-text hints for the receiving agent, max 256 chars — for example retry on timeout or require_semantic_match=true.

Assembled, a memory lookup looks like this:

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

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

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

{ "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)

{
  "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.

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.

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

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.

Related

• Agent Transmission Protocol reference — full tag spec, ActionType catalog, and every ATP REST endpoint
• Trust scoring and access levels — how senderId trust affects which ActionType values an agent is actually allowed to issue
• Multi-agent communication — how TargetZone and routing modes interact