API Reference - Artemis City

Overview

Artemis City exposes three primary API surfaces:

Agent API: Task submission and execution
ATP (Agent Transmission Protocol): Structured inter-agent messaging
System APIs: Registry, Memory Bus, Governance (admin-only)

All APIs use HTTP/JSON for REST endpoints and support gRPC where noted.

Agent Transmission Protocol (ATP)

ATP is the structured message format for agent-to-agent communication and kernel-to-agent direction.

ATP Message Format

#Mode <mode>
#Context <context_id>
#Priority <priority_level>
#ActionType <action_type>
#TargetZone <zone_identifier>
#SpecialNotes <notes>

<message_body>

ATP Tags Specification

Tag	Values	Required	Example	Purpose
`#Mode`	`direct`, `batch`, `stream`, `async`	Yes	`#Mode direct`	Communication mode
`#Context`	UUID, string (max 64 chars)	Yes	`#Context exec-2026-02-21-xyz`	Trace/correlation ID
`#Priority`	`critical` (0), `high` (1), `normal` (2), `low` (3)	Yes	`#Priority high`	Queue priority
`#ActionType`	See section below	Yes	`#ActionType query`	What agent should do
`#TargetZone`	`kernel`, `registry`, `memory`, `sandbox`, `governance`	Yes	`#TargetZone memory`	System component target
`#SpecialNotes`	String (max 256 chars)	No	`#SpecialNotes retry on timeout`	Metadata/hints

ActionType Values

Query Operations:

query: Read/lookup operation
search: Semantic or keyword search
list: Enumerate items
get_status: Check current state

Modification Operations:

create: Insert new record
update: Modify existing record
delete: Remove record
upsert: Create or update

Execution Operations:

execute: Run task/agent
schedule: Queue for later execution
cancel: Abort running task
retry: Re-execute failed task

Management Operations:

register: Register agent or capability
revoke: Remove registration
approve: Approve pending action
reject: Deny pending action

Governance Operations:

propose_update: Submit self-update
rollback: Revert to checkpoint
override: Bypass policy check

ATP Message Examples

Example 1: Query Task from Memory Bus

#Mode direct
#Context task-exec-2026-02-21-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,
  "filters": {
    "hebbian_weight_min": 0.6,
    "created_after": "2026-02-15T00:00:00Z"
  }
}

Example 2: Submit Task for Execution (Kernel)

#Mode direct
#Context user-request-2026-02-21-xyz789
#Priority normal
#ActionType execute
#TargetZone kernel

{
  "task": {
    "id": "task-uuid",
    "type": "text-analysis",
    "input": "Analyze the following document...",
    "required_capabilities": ["nlp", "sentiment-analysis"],
    "timeout_seconds": 300,
    "agent_preference": null
  }
}

Example 3: Batch Agent Communication

#Mode batch
#Context batch-sync-2026-02-21-batch001
#Priority normal
#ActionType update
#TargetZone registry

{
  "operations": [
    {
      "agent_id": "agent-uuid-1",
      "field": "accuracy_score",
      "value": 0.92
    },
    {
      "agent_id": "agent-uuid-2",
      "field": "efficiency_score",
      "value": 0.87
    }
  ]
}

Example 4: Async Governance Update Proposal

#Mode async
#Context update-proposal-2026-02-21-tier2
#Priority high
#ActionType propose_update
#TargetZone governance
#SpecialNotes trust_score=0.85, risk_tier=monitored

{
  "update_id": "uuid",
  "agent_id": "uuid",
  "update_type": "patch",
  "description": "Fix memory leak in task router",
  "changes": {
    "files_modified": ["src/kernel.py"],
    "lines_added": 15,
    "lines_deleted": 8
  },
  "checkpoint_id": "uuid"
}

Kernel API

Submit Task

Endpoint: POST /api/v1/tasks Request:

{
  "id": "task-uuid (optional, generated if omitted)",
  "type": "string (required, task type identifier)",
  "input": "any (required, task input)",
  "required_capabilities": ["string"],
  "timeout_seconds": 300,
  "agent_preference": "uuid (optional, preferred agent)",
  "metadata": {
    "user_id": "uuid",
    "priority": "high|normal|low",
    "retry_count": 0,
    "tags": ["tag1", "tag2"]
  }
}

Response (202 Accepted):

{
  "task_id": "uuid",
  "status": "queued|executing|pending_approval",
  "estimated_start": "2026-02-21T10:30:00Z",
  "estimated_completion": "2026-02-21T10:35:00Z"
}

Get Task Status

Endpoint: GET /api/v1/tasks/{task_id} Response:

{
  "task_id": "uuid",
  "status": "queued|executing|completed|failed|aborted",
  "assigned_agent": "uuid",
  "start_time": "2026-02-21T10:30:00Z",
  "completion_time": "2026-02-21T10:32:45Z",
  "duration_ms": 165000,
  "result": "any",
  "error": null
}

Cancel Task

Endpoint: POST /api/v1/tasks/{task_id}/cancel Response:

{
  "task_id": "uuid",
  "status": "cancelled",
  "cancelled_at": "2026-02-21T10:31:00Z"
}

List Tasks

Endpoint: GET /api/v1/tasks?status=completed&limit=100&offset=0 Query Parameters:

status: Filter by status
agent_id: Filter by assigned agent
created_after: ISO 8601 timestamp
limit: Result limit (default: 100, max: 1000)
offset: Pagination offset

Response:

{
  "tasks": [
    {
      "task_id": "uuid",
      "status": "completed",
      "assigned_agent": "uuid",
      "type": "string",
      "created_at": "2026-02-21T10:00:00Z",
      "completed_at": "2026-02-21T10:02:45Z"
    }
  ],
  "total": 5000,
  "limit": 100,
  "offset": 0
}

Memory Bus API

Write Document

Endpoint: POST /api/v1/memory/write Request:

{
  "operation": "write|update|delete",
  "vault": "vault-id",
  "document": {
    "path": "path/to/document.md",
    "content": "# Heading\n\nMarkdown content",
    "frontmatter": {
      "hebbian_weights": {
        "agent_uuid": 0.75
      },
      "tags": ["tag1", "tag2"],
      "created_at": "2026-02-21T10:00:00Z"
    }
  },
  "metadata": {
    "source_agent": "uuid",
    "priority": "high|normal|low",
    "conflict_resolution": "last_write_wins|abort|merge"
  }
}

Response (200 OK):

{
  "status": "success|conflict",
  "write_id": "uuid",
  "timestamp": "2026-02-21T10:30:00.123Z",
  "latency_ms": 145,
  "content_hash": "sha256_hash",
  "sync_pending": true,
  "estimated_sync_completion": "2026-02-21T10:30:00.300Z"
}

Read Document (Exact)

Endpoint: GET /api/v1/memory/read/exact?path={path} Response:

{
  "status": "success|not_found",
  "document": {
    "path": "path/to/document.md",
    "content": "# Heading\n\nMarkdown content",
    "frontmatter": {
      "hebbian_weights": {},
      "created_at": "2026-02-21T10:00:00Z"
    }
  },
  "latency_ms": 45
}

Search Documents (Keyword)

Endpoint: POST /api/v1/memory/search/keyword Request:

{
  "terms": ["term1", "term2"],
  "fields": ["title", "tags", "content"],
  "match_mode": "all|any",
  "limit": 20
}

Response:

{
  "matches": [
    {
      "path": "path/to/document.md",
      "title": "Document Title",
      "excerpt": "...snippet of matching content...",
      "relevance_score": 0.95
    }
  ],
  "total_matches": 1,
  "search_latency_ms": 125
}

Search Documents (Semantic)

Endpoint: POST /api/v1/memory/search/semantic Request:

{
  "query": "Find information about data processing",
  "embedding": "optional_precomputed_vector",
  "top_k": 10,
  "filters": {
    "hebbian_weight_min": 0.3,
    "created_after": "2026-01-01T00:00:00Z"
  }
}

Response:

{
  "matches": [
    {
      "path": "path/to/document.md",
      "content_preview": "First 200 chars of content",
      "similarity_score": 0.92,
      "source_level": "vector_store",
      "hebbian_weights": {
        "agent_uuid": 0.75
      }
    }
  ],
  "total_matches": 15,
  "search_latency_ms": 275
}

Get Memory Health

Endpoint: GET /api/v1/memory/health Response:

{
  "status": "healthy|degraded|unhealthy",
  "components": {
    "obsidian": {
      "status": "up",
      "latency_ms": 5,
      "sync_lag_ms": 0
    },
    "vector_store": {
      "status": "up",
      "latency_ms": 150,
      "sync_lag_ms": 45
    }
  },
  "stats": {
    "total_documents": 10523,
    "total_size_mb": 256,
    "cache_hit_ratio": 0.75,
    "last_sync": "2026-02-21T10:30:15Z"
  }
}

Agent Registry API

Register Agent

Endpoint: POST /api/v1/registry/agents Request:

{
  "name": "string (required, agent name)",
  "capabilities": ["string"],
  "alignment_score": 0.85,
  "accuracy_score": 0.92,
  "efficiency_score": 0.88,
  "trust_tier": "auto|monitored|human",
  "sandbox_whitelist": {
    "tools": [
      {
        "name": "file_read",
        "paths": ["/data/public/**"],
        "operations": ["read"],
        "rate_limit": 100
      }
    ],
    "network": {
      "allowlist": ["api.example.com"],
      "ports": [80, 443]
    }
  }
}

Response (201 Created):

{
  "agent_id": "uuid",
  "name": "string",
  "status": "active",
  "created_at": "2026-02-21T10:30:00Z"
}

Get Agent

Endpoint: GET /api/v1/registry/agents/{agent_id} Response:

{
  "agent_id": "uuid",
  "name": "string",
  "capabilities": ["string"],
  "alignment_score": 0.85,
  "accuracy_score": 0.92,
  "efficiency_score": 0.88,
  "trust_tier": "auto|monitored|human",
  "trust_score": 0.89,
  "status": "active|suspended|quarantined",
  "violation_count": 0,
  "last_task": "2026-02-21T10:25:00Z",
  "updated_at": "2026-02-21T10:30:00Z"
}

List Agents

Endpoint: GET /api/v1/registry/agents?capability=nlp&status=active&limit=100 Query Parameters:

capability: Filter by capability
status: Filter by status
trust_tier: Filter by tier
limit: Result limit

Response:

{
  "agents": [
    {
      "agent_id": "uuid",
      "name": "string",
      "capabilities": ["string"],
      "trust_score": 0.89,
      "status": "active"
    }
  ],
  "total": 45,
  "limit": 100,
  "offset": 0
}

Update Agent Scores

Endpoint: PATCH /api/v1/registry/agents/{agent_id} Request:

{
  "alignment_score": 0.85,
  "accuracy_score": 0.92,
  "efficiency_score": 0.88
}

Response:

{
  "agent_id": "uuid",
  "alignment_score": 0.85,
  "accuracy_score": 0.92,
  "efficiency_score": 0.88,
  "updated_at": "2026-02-21T10:30:00Z"
}

Get Agent Violations

Endpoint: GET /api/v1/registry/agents/{agent_id}/violations Response:

{
  "agent_id": "uuid",
  "violation_count": 3,
  "quarantined": true,
  "violations": [
    {
      "violation_id": "uuid",
      "timestamp": "2026-02-21T10:15:00Z",
      "type": "unauthorized_tool",
      "details": "Attempted access to /etc/passwd"
    }
  ]
}

Clear Agent Violations

Endpoint: POST /api/v1/registry/agents/{agent_id}/clear-violations Request:

{
  "override_tier": "monitored",
  "rationale": "Manual review confirms safe behavior"
}

Response:

{
  "agent_id": "uuid",
  "violation_count": 0,
  "quarantined": false,
  "overridden_by": "admin_uuid",
  "override_timestamp": "2026-02-21T10:30:00Z"
}

Governance API

Propose Update

Endpoint: POST /api/v1/governance/updates Request: (See ATP Example 4 in section above) Response (202 Accepted):

{
  "update_id": "uuid",
  "status": "submitted|approved|rejected",
  "tier": 1,
  "approval_deadline": "2026-02-21T10:35:00Z"
}

Get Update Status

Endpoint: GET /api/v1/governance/updates/{update_id} Response:

{
  "update_id": "uuid",
  "agent_id": "uuid",
  "status": "submitted|approved|rejected|deploying|deployed|rolled_back",
  "tier": 2,
  "submitted_at": "2026-02-21T10:30:00Z",
  "approved_at": "2026-02-21T11:00:00Z",
  "deployed_at": "2026-02-21T11:05:00Z",
  "test_results": {
    "unit_tests": { "passed": 1247, "failed": 0 },
    "integration_tests": { "passed": 156, "failed": 0 }
  }
}

List Pending Approvals

Endpoint: GET /api/v1/governance/approvals?tier=2&status=pending Response:

{
  "pending": [
    {
      "update_id": "uuid",
      "agent_id": "uuid",
      "tier": 2,
      "submitted_at": "2026-02-21T10:30:00Z",
      "deadline": "2026-02-21T11:30:00Z"
    }
  ],
  "count": 2,
  "overdue": 0
}

Approve Update

Endpoint: POST /api/v1/governance/updates/{update_id}/approve Request:

{
  "approved_by": "admin_uuid",
  "rationale": "Code review passed, all tests green",
  "override_risk": false
}

Response:

{
  "update_id": "uuid",
  "status": "approved",
  "deployment_scheduled": true,
  "deployment_time": "2026-02-21T11:05:00Z"
}

Reject Update

Endpoint: POST /api/v1/governance/updates/{update_id}/reject Request:

{
  "rejected_by": "admin_uuid",
  "reason": "Breaking API change not justified",
  "feedback": "Please refactor to maintain backwards compatibility"
}

Response:

{
  "update_id": "uuid",
  "status": "rejected",
  "rejected_at": "2026-02-21T10:35:00Z"
}

Propose Rollback

Endpoint: POST /api/v1/governance/rollbacks Request:

{
  "checkpoint_id": "uuid",
  "initiated_by": "admin_uuid",
  "reason": "error_detected",
  "details": "Anomaly: error rate > 5%"
}

Response (202 Accepted):

{
  "rollback_id": "uuid",
  "checkpoint_id": "uuid",
  "status": "initiated|in_progress|completed|failed",
  "estimated_completion": "2026-02-21T10:45:00Z"
}

Get Rollback Status

Endpoint: GET /api/v1/governance/rollbacks/{rollback_id} Response:

{
  "rollback_id": "uuid",
  "checkpoint_id": "uuid",
  "status": "completed",
  "initiated_at": "2026-02-21T10:35:00Z",
  "completed_at": "2026-02-21T10:42:00Z",
  "verified": true,
  "notes": "System restored to stable state"
}

Hebbian Learning API

Get Hebbian Weights

Endpoint: GET /api/v1/hebbian/weights?agent_id={agent_id} Response:

{
  "agent_id": "uuid",
  "weights": {
    "task_type_1": 0.75,
    "task_type_2": 0.45,
    "task_type_3": 0.92
  },
  "last_updated": "2026-02-21T10:30:00Z"
}

Get Learning History

Endpoint: GET /api/v1/hebbian/history/{agent_id}?limit=100 Response:

{
  "agent_id": "uuid",
  "history": [
    {
      "timestamp": "2026-02-21T10:25:00Z",
      "task_type": "text-analysis",
      "delta": 1,
      "result": "success",
      "weight_before": 0.74,
      "weight_after": 0.75
    }
  ],
  "total_entries": 542,
  "limit": 100
}

ATP REST endpoints

In addition to the ATP message format above, the API exposes endpoints for building, validating, routing, and inspecting ATP messages directly over HTTP. Use these when you want the server to handle ATP queueing and routing instead of constructing raw messages yourself. All ATP endpoints require authentication.

Send ATP message

Endpoint: POST /api/v1/atp/send Submits a structured ATP message. The server validates the message, assigns it a messageId, and queues it for routing. Request:

{
  "header": {
    "mode": "direct",
    "context": "exec-2026-06-04-abc",
    "priority": "high",
    "actionType": "query",
    "targetZone": "memory",
    "senderId": "agent-uuid"
  },
  "payload": {
    "content": "Find tasks related to data processing"
  }
}

Response:

{
  "success": true,
  "messageId": "uuid"
}

Route ATP message

Endpoint: POST /api/v1/atp/route Resolves a message to the agent(s) that would handle it without dispatching it. Use this to preview routing decisions. Request:

{
  "message": {
    "header": { "mode": "direct", "context": "...", "actionType": "execute", "targetZone": "kernel" },
    "payload": { "content": "..." }
  }
}

Response:

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

Validate ATP message

Endpoint: POST /api/v1/atp/validate Checks an ATP message for structural and field-level errors without sending it. Useful for client-side form validation or CI tooling. Response:

{
  "success": true,
  "data": {
    "valid": true,
    "errors": []
  }
}

Format ATP message

Endpoint: POST /api/v1/atp/format Accepts the same body as POST /api/v1/atp/send and returns the formatted ATP wire string alongside the stored message. Use this to inspect what a message looks like on the wire.

Inspect modes, priorities, and action types

Endpoint	Returns
`GET /api/v1/atp/modes`	Allowed values for `header.mode`.
`GET /api/v1/atp/priorities`	Allowed values for `header.priority`.
`GET /api/v1/atp/action-types`	Allowed values for `header.actionType`.
`GET /api/v1/atp/template`	A starter ATP message template with required and optional fields annotated.

Look up messages, responses, and queue depth

Endpoint	Purpose
`GET /api/v1/atp/message/{id}`	Fetch a previously submitted ATP message by ID.
`GET /api/v1/atp/response/{id}`	Fetch the response generated for a given message ID.
`GET /api/v1/atp/queue`	Snapshot of the current ATP queue (depth, oldest message, per-priority counts).

LLM API

The LLM API is the gateway agents use to call configured LLM providers (Anthropic Claude, OpenAI, local providers via Exo, and others). It centralizes provider configuration, model selection, ATP-aware prompting, and token usage tracking. Use the LLM API when you want:

A single HTTP surface across multiple providers and models.
Streaming responses for chat UIs.
ATP-formatted prompts handled and routed automatically.
Per-provider usage and quota tracking.

All endpoints require authentication.

Chat completion

Endpoint: POST /api/v1/llm/chat Sends a multi-turn chat completion to the selected provider. Request:

{
  "messages": [
    { "role": "system", "content": "You are a routing assistant for Artemis City." },
    { "role": "user", "content": "Summarize the last governance update." }
  ],
  "model": "claude-3-5-sonnet",
  "options": {
    "temperature": 0.2,
    "max_tokens": 512
  }
}

Response:

{
  "success": true,
  "data": {
    "model": "claude-3-5-sonnet",
    "content": "The last governance update...",
    "usage": {
      "input_tokens": 142,
      "output_tokens": 88
    }
  }
}

Text completion

Endpoint: POST /api/v1/llm/complete Single-prompt completion for providers and models that support raw text completion. Request:

{
  "prompt": "Draft a one-line release note for the trust scoring change.",
  "model": "claude-3-5-haiku",
  "options": { "max_tokens": 64 }
}

Embeddings

Endpoint: POST /api/v1/llm/embed Generates embeddings for use with the memory bus or the semantic search endpoints. Request:

{
  "text": "Find tasks related to data processing",
  "model": "text-embedding-3-small"
}

Response:

{
  "success": true,
  "data": {
    "model": "text-embedding-3-small",
    "embedding": [0.0123, -0.0456, "..."],
    "dimensions": 1536
  }
}

Stream chat completion

Endpoint: POST /api/v1/llm/stream Streams a chat completion using Server-Sent Events (SSE). The request body matches POST /api/v1/llm/chat. The response sets Content-Type: text/event-stream and emits one data: line per chunk, terminated by data: [DONE].

data: {"delta":"The "}
data: {"delta":"last "}
data: {"delta":"governance update..."}
data: [DONE]

List models

Endpoint: GET /api/v1/llm/models Returns the models that the API can route to across all configured providers.

List providers

Endpoint: GET /api/v1/llm/providers Returns providers that have been configured on the server (for example anthropic, openai, exo) and whether each is currently reachable.

Configure provider

Endpoint: POST /api/v1/llm/provider Registers or updates credentials and base URL for a provider at runtime. Prefer environment variables for long-lived credentials; use this endpoint for runtime overrides such as rotating an API key or pointing at a local Exo instance. Request:

{
  "provider": "anthropic",
  "apiKey": "sk-ant-...",
  "baseUrl": "https://api.anthropic.com",
  "options": {
    "default_model": "claude-3-5-sonnet"
  }
}

Process ATP message through LLM

Endpoint: POST /api/v1/llm/atp Hands an ATP message to the LLM router. The server picks an appropriate model, executes the prompt encoded in the message, and returns the LLM response together with the original ATP context. Use this when you want ATP routing semantics and LLM execution in a single call. Request:

{
  "atpMessage": {
    "header": {
      "mode": "direct",
      "context": "summarize-2026-06-04",
      "priority": "normal",
      "actionType": "query",
      "targetZone": "kernel"
    },
    "payload": { "content": "Summarize today's task failures." }
  },
  "model": "claude-3-5-sonnet",
  "agentId": "agent-uuid"
}

Usage statistics

Endpoint: GET /api/v1/llm/usage?startDate=2026-06-01&endDate=2026-06-04&provider=anthropic Returns aggregated token usage and cost estimates. All query parameters are optional; omit provider to receive a breakdown across every configured provider.

Trust API

The Trust API exposes the runtime trust store that gates what each agent (or other entity) is allowed to do. Use it to read or adjust an entity’s trust score, record successes and failures that drive the score, check which operations an entity is permitted to perform, and read or update the Hebbian connection weights between agents. Trust scores are floats in the range [0, 1]. Each score maps to a trust level that controls allowed operations. Successes and failures move the score; idle entities decay over time. All endpoints require authentication.

Get trust report

Endpoint: GET /api/v1/trust/report Returns a snapshot of every tracked entity, its current score, level, and recent activity. Useful for dashboards and audits.

Get trust score

Endpoint: GET /api/v1/trust/{entityId} Returns 404 if the entity is unknown. Response:

{
  "success": true,
  "data": {
    "entityId": "agent-uuid",
    "entityType": "agent",
    "score": 0.82,
    "level": "HIGH",
    "lastUpdated": "2026-06-04T10:30:00Z"
  }
}

Set trust score

Endpoint: PUT /api/v1/trust/{entityId} Sets an explicit score. Use this for manual overrides — for normal operation, prefer recording successes and failures so the score evolves from observed behavior. Request:

{
  "score": 0.75,
  "entityType": "agent"
}

score must be between 0 and 1. entityType defaults to agent.

Record success

Endpoint: POST /api/v1/trust/{entityId}/success Increments the entity’s trust score after a successful operation. Default reinforcement is +0.02; pass amount to override. Request:

{
  "amount": 0.02
}

Response:

{
  "success": true,
  "data": {
    "entityId": "agent-uuid",
    "newScore": 0.84,
    "delta": 0.02
  }
}

Record failure

Endpoint: POST /api/v1/trust/{entityId}/failure Decrements the entity’s trust score after a failed or unsafe operation. Default penalty is -0.05; pass amount to override. Request:

{
  "amount": 0.05
}

Get permissions

Endpoint: GET /api/v1/trust/{entityId}/permissions Returns the operations the entity is currently allowed to perform, derived from its trust level. Response:

{
  "success": true,
  "data": {
    "entityId": "agent-uuid",
    "level": "HIGH",
    "operations": ["read", "write", "search", "tag", "update", "frontmatter"]
  }
}

Check a specific operation

Endpoint: POST /api/v1/trust/{entityId}/can-perform Use this in gating code paths before dispatching an operation. Request:

{
  "operation": "delete"
}

Response:

{
  "success": true,
  "data": {
    "entityId": "agent-uuid",
    "operation": "delete",
    "allowed": false
  }
}

Get trust levels

Endpoint: GET /api/v1/trust/levels Returns the trust level definitions used to map scores to operations, plus the decay and reinforcement parameters. Use this to render UI legends or to keep clients in sync with server policy. Response:

{
  "success": true,
  "data": {
    "levels": [
      { "name": "FULL", "range": "0.9 - 1.0", "operations": ["read", "write", "delete", "search", "tag", "update", "frontmatter"] },
      { "name": "HIGH", "range": "0.7 - 0.9", "operations": ["read", "write", "search", "tag", "update", "frontmatter"] },
      { "name": "MEDIUM", "range": "0.5 - 0.7", "operations": ["read", "write", "search", "tag"] },
      { "name": "LOW", "range": "0.3 - 0.5", "operations": ["read", "search"] },
      { "name": "UNTRUSTED", "range": "0.0 - 0.3", "operations": [] }
    ],
    "decayRate": "1% per day",
    "reinforcement": "+0.02 per success",
    "penalty": "-0.05 per failure"
  }
}

Get Hebbian connection weights

Endpoint: GET /api/v1/trust/hebbian/weights Returns the matrix of agent-to-agent Hebbian weights used for co-activation-based routing. See Hebbian learning for the underlying model.

Update a Hebbian connection weight

Endpoint: PUT /api/v1/trust/hebbian/weights Reinforces or weakens the connection between two agents. Positive delta strengthens the link; negative delta weakens it. Request:

{
  "agent1": "planner-uuid",
  "agent2": "summarizer-uuid",
  "delta": 0.05
}

Response:

{
  "success": true,
  "data": {
    "connection": "planner-uuid-summarizer-uuid",
    "newWeight": 0.62,
    "delta": 0.05
  }
}

Health checks

The API exposes lightweight, unauthenticated health endpoints suitable for load balancers and orchestration probes:

Endpoint	Purpose
`GET /health` and `GET /api/v1/health`	Basic liveness with service name and version.
`GET /api/v1/health/detailed`	Component-level status for the API, MCP server, vault, and agents. Returns `503` when any component is unavailable.
`GET /api/v1/health/ready`	Readiness probe (`{"ready": true}`).
`GET /api/v1/health/live`	Liveness probe (`{"alive": true}`).

Error Responses

All error responses follow this format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      "field": "optional field-specific errors"
    },
    "request_id": "uuid (for tracing)"
  }
}

Common Error Codes

Code	HTTP	Meaning
`INVALID_REQUEST`	400	Malformed request
`UNAUTHORIZED`	401	Missing/invalid authentication
`FORBIDDEN`	403	Insufficient permissions
`NOT_FOUND`	404	Resource not found
`CONFLICT`	409	Write conflict
`RATE_LIMITED`	429	Rate limit exceeded
`SERVICE_UNAVAILABLE`	503	Service temporarily down
`TIMEOUT`	504	Request timeout

Rate Limiting

All endpoints are subject to rate limiting:

Default: 100 requests/minute per API key
Burst: 200 requests for 10 seconds
Headers:
- X-RateLimit-Limit: Requests per minute
- X-RateLimit-Remaining: Remaining requests
- X-RateLimit-Reset: Unix timestamp of reset

Authentication

Authenticate with either an Authorization: Bearer token or an X-API-Key header:

Authorization: Bearer <api_key>

X-API-Key: <api_key>

Health endpoints (/health, /api/v1/health/*) are public. Every other endpoint requires a valid key.

Configuring API keys

API keys are loaded from environment variables at startup. Each key encodes its user, role, and permissions in a single value:

ARTEMIS_API_KEY_<NAME>=<key>:<role>:<perm1,perm2,...>

For example:

ARTEMIS_API_KEY_ADMIN=sk-live-abc123:admin:read,write,delete,admin
ARTEMIS_API_KEY_AGENT_PLANNER=sk-live-def456:agent:read,write

If no ARTEMIS_API_KEY_* variables are set, the server falls back to MCP_API_KEY with full admin permissions. Set explicit per-user keys in any production environment.

Webhook Events

Subscribe to events via POST /api/v1/webhooks:

{
  "url": "https://example.com/webhook",
  "events": ["task.completed", "update.approved", "agent.quarantined"]
}

Event payload:

{
  "event": "task.completed",
  "timestamp": "2026-02-21T10:30:00Z",
  "data": {
    "task_id": "uuid",
    "status": "completed",
    "result": "any"
  }
}

Last modified on July 16, 2026

​Overview

​Agent Transmission Protocol (ATP)

​ATP Message Format

​ATP Tags Specification

​ActionType Values

​ATP Message Examples

​Example 1: Query Task from Memory Bus

​Example 2: Submit Task for Execution (Kernel)

​Example 3: Batch Agent Communication

​Example 4: Async Governance Update Proposal

​Kernel API

​Submit Task

​Get Task Status

​Cancel Task

​List Tasks

​Memory Bus API

​Write Document

​Read Document (Exact)

​Search Documents (Keyword)

​Search Documents (Semantic)

​Get Memory Health

​Agent Registry API

​Register Agent

​Get Agent

​List Agents

​Update Agent Scores

​Get Agent Violations

​Clear Agent Violations

​Governance API

​Propose Update

​Get Update Status

​List Pending Approvals

​Approve Update

​Reject Update

​Propose Rollback

​Get Rollback Status

​Hebbian Learning API

​Get Hebbian Weights

​Get Learning History

​ATP REST endpoints

​Send ATP message

​Route ATP message

​Validate ATP message

​Format ATP message

​Inspect modes, priorities, and action types

​Look up messages, responses, and queue depth

​LLM API

​Chat completion

​Text completion

​Embeddings

​Stream chat completion

​List models

​List providers

​Configure provider

​Process ATP message through LLM

​Usage statistics

​Trust API

​Get trust report

​Get trust score

​Set trust score

​Record success

​Record failure

​Get permissions

​Check a specific operation

​Get trust levels

​Get Hebbian connection weights

​Update a Hebbian connection weight

​Health checks

​Error Responses

​Common Error Codes

​Rate Limiting

​Authentication

​Configuring API keys

​Webhook Events

Overview

Agent Transmission Protocol (ATP)

ATP Message Format

ATP Tags Specification

ActionType Values

ATP Message Examples

Example 1: Query Task from Memory Bus

Example 2: Submit Task for Execution (Kernel)

Example 3: Batch Agent Communication

Example 4: Async Governance Update Proposal

Kernel API

Submit Task

Get Task Status

Cancel Task

List Tasks

Memory Bus API

Write Document

Read Document (Exact)

Search Documents (Keyword)

Search Documents (Semantic)

Get Memory Health

Agent Registry API

Register Agent

Get Agent

List Agents

Update Agent Scores

Get Agent Violations

Clear Agent Violations

Governance API

Propose Update

Get Update Status

List Pending Approvals

Approve Update

Reject Update

Propose Rollback

Get Rollback Status

Hebbian Learning API

Get Hebbian Weights

Get Learning History

ATP REST endpoints

Send ATP message

Route ATP message

Validate ATP message

Format ATP message

Inspect modes, priorities, and action types

Look up messages, responses, and queue depth

LLM API

Chat completion

Text completion

Embeddings

Stream chat completion

List models

List providers

Configure provider

Process ATP message through LLM

Usage statistics

Trust API

Get trust report

Get trust score

Set trust score

Record success

Record failure

Get permissions

Check a specific operation

Get trust levels

Get Hebbian connection weights

Update a Hebbian connection weight

Health checks

Error Responses

Common Error Codes

Rate Limiting

Authentication

Configuring API keys

Webhook Events