API Reference - Artemis City

Overview

Artemis City exposes three primary API surfaces:

Agent API: Task submission and execution
ATP (Artemis 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.

Artemis 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} Returns a single task by exact ID regardless of execution status. Use this to hydrate deep links to a task detail view (for example /tasks/:taskId in the console) after the task has moved out of the pending queue. The list endpoint (GET /api/v1/tasks) only returns pending work; this endpoint remains addressable for completed, failed, and cancelled tasks. The identifier is matched against parsed task metadata only; it is never used to construct a filesystem path. Requests with an empty or oversized (> 255 chars) task_id return 404. 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
}

Get task activity trail

Endpoint: GET /api/v1/tasks/{task_id}/activity Returns the governed activity trail for one exact task: task metadata, resolved routing decision, the ordered execution event log, and any reports produced by the task. The activity trail is a read-only projection over the task note, the canonical run log, and server-generated report summaries. Use this endpoint to power a task detail or audit view that needs to answer:

Which agent handled the task, under what capability and provider?
What routing decision selected that agent?
What ordered events did the run emit, with timing and provenance IDs?
Which reports did the run produce?

Events are matched by exact task_id against parsed event metadata before being returned, so a similarly named task cannot borrow another task’s provenance. Query parameters:

limit: Maximum number of events to return. Integer between 1 and 500. Defaults to 200. Requests outside that range return 400.

Errors:

400 — limit is not between 1 and 500.
404 — task_id is empty, exceeds 255 characters, or no matching task and no matching events exist.
500 — the task index or run-log database could not be read, or reports could not be linked.

Response:

{
  "task_id": "task-uuid",
  "task": {
    "task_id": "task-uuid",
    "status": "completed",
    "relative_path": "AgentInput/task-2026-08-05.md"
  },
  "status": "completed",
  "provenance_id": "prov-uuid",
  "agent_name": "planner",
  "capability": "nlp",
  "routing": {
    "chosen_agent": "planner",
    "score": 0.87,
    "rationale": "matched capability=nlp with highest Hebbian weight"
  },
  "provider": "anthropic",
  "outcome_class": "success",
  "learning_eligible": true,
  "reports": [
    {
      "filename": "task-uuid-summary.md",
      "task_id": "task-uuid",
      "generated_at": "2026-08-05T12:34:56Z"
    }
  ],
  "events": [
    {
      "run_id": "run-uuid",
      "timestamp": "2026-08-05T12:34:50Z",
      "event_type": "prompt_received",
      "component": "kernel",
      "message": "Prompt accepted for routing",
      "metadata": { "task_id": "task-uuid" },
      "duration_ms": null,
      "prov_id": "prov-uuid",
      "parent_prov_id": null
    },
    {
      "run_id": "run-uuid",
      "timestamp": "2026-08-05T12:34:51Z",
      "event_type": "routing_decision",
      "component": "router",
      "message": "Selected agent planner",
      "metadata": {
        "task_id": "task-uuid",
        "decision": {
          "chosen_agent": "planner",
          "score": 0.87
        }
      },
      "duration_ms": 12,
      "prov_id": "prov-uuid-2",
      "parent_prov_id": "prov-uuid"
    }
  ]
}

Example:

curl -H "X-API-Key: $ARTEMIS_API_KEY" \
  "https://api.artemiscity.com/api/v1/tasks/task-uuid/activity?limit=50"

Any of provenance_id, agent_name, capability, routing, provider, outcome_class, and learning_eligible may be null when the corresponding event has not been emitted yet — for example while a task is still queued. reports is an empty array until the task produces a report.

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
}

Get task by ID (dashboard read API)

Endpoint: GET /api/tasks/{task_id} Returns one parsed task note by exact task ID across every status (pending, executing, completed, failed). Use this instead of GET /api/v1/tasks when you need a task to stay addressable after execution moves it out of the pending queue. This is what the dashboard’s task detail page (/tasks/:taskId) calls to render a refreshable deep link. The task ID is compared against parsed task metadata only. It is never concatenated with the vault root or passed to a note-read operation, so a similarly named task cannot leak another task’s content. IDs longer than 255 characters are rejected with 404. Authentication: Requires the dashboard API key. Response (200 OK):

{
  "task_id": "task_12345",
  "status": "completed",
  "relative_path": "agent-input/task_12345.md",
  "title": "Summarize incident report",
  "priority": "high",
  "created_at": "2026-08-05T10:00:00Z"
}

Errors:

404 Not Found — no task note matches the given ID, or the ID is empty or longer than 255 characters.
500 Internal Server Error — the vault could not be read.

Example:

curl -H "X-API-Key: $ARTEMIS_API_KEY" \
  https://api.artemiscity.com/api/tasks/task_12345

Get task activity trail

Endpoint: GET /api/tasks/{task_id}/activity Returns the governed activity trail for one exact task ID. The response stitches together the task record, the routing decision, the provenance chain, every run-log event whose metadata matches that task ID, and any reports the task produced. Use this to render a task detail or replay view when you need routing, dispatch, memory, and learning events correlated by parent and child provenance ID. It is the read path behind the dashboard’s task activity page (/tasks/:taskId/activity). Events are read from the canonical run log and filtered by exact task_id in metadata, so a task cannot borrow another task’s provenance. The browser supplies only the task ID; it cannot select a note path or report filename. Authentication: Requires the dashboard API key. Query Parameters:

limit: Maximum number of events to return. Integer between 1 and 500. Defaults to 200.

Response (200 OK):

{
  "task_id": "task_12345",
  "task": {
    "task_id": "task_12345",
    "status": "completed",
    "relative_path": "agent-input/task_12345.md",
    "title": "Summarize incident report"
  },
  "status": "completed",
  "provenance_id": "prov_abc123",
  "agent_name": "summarizer_v2",
  "capability": "text_summarization",
  "routing": {
    "chosen_agent": "summarizer_v2",
    "candidates": [
      { "agent": "summarizer_v2", "score": 0.92 },
      { "agent": "summarizer_v1", "score": 0.78 }
    ]
  },
  "provider": "exo",
  "outcome_class": "success",
  "learning_eligible": true,
  "reports": [
    {
      "filename": "task_12345_report.md",
      "task_id": "task_12345",
      "created_at": "2026-08-05T10:02:45Z"
    }
  ],
  "events": [
    {
      "run_id": "run_789",
      "timestamp": "2026-08-05T10:00:01Z",
      "event_type": "prompt_received",
      "component": "kernel",
      "message": "Task received",
      "metadata": { "task_id": "task_12345" },
      "duration_ms": null,
      "prov_id": "prov_abc123",
      "parent_prov_id": null
    },
    {
      "run_id": "run_789",
      "timestamp": "2026-08-05T10:00:02Z",
      "event_type": "routing_decision",
      "component": "router",
      "message": "Selected summarizer_v2",
      "metadata": {
        "task_id": "task_12345",
        "decision": { "chosen_agent": "summarizer_v2" }
      },
      "duration_ms": 45,
      "prov_id": "prov_abc124",
      "parent_prov_id": "prov_abc123"
    }
  ]
}

Response fields:

task: The parsed task record, or null if only run-log events remain for the ID.
status: Latest known status. Taken from the task record and overridden by any later status field emitted in event metadata.
provenance_id: Root provenance ID for the task. Resolved from the first prompt_received event and used to correlate downstream events.
agent_name, capability, provider: The agent, required capability, and provider recorded on the routing decision or on later events.
routing: The full routing decision object as emitted by the router, when available.
outcome_class, learning_eligible: Learning gates from the outcome event. learning_eligible controls whether Hebbian weights update for this task.
reports: Reports whose task_id matches this task, in the same shape returned by GET /api/reports.
events: The matching run-log events in ascending chronological order, capped by limit.

Errors:

400 Bad Request — limit is outside the range 1–500.
404 Not Found — no task record and no matching events exist for the given ID, or the ID is empty or longer than 255 characters.
500 Internal Server Error — the run log or reports could not be read.

Example:

curl -H "X-API-Key: $ARTEMIS_API_KEY" \
  "https://api.artemiscity.com/api/tasks/task_12345/activity?limit=100"

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
  }
}

Monitoring API

The Monitoring API powers the Monitoring dashboard page. It exposes governance state straight from the SQLite stores and a slimmed view of Prometheus alerts and scrape targets. Both endpoints require authentication with X-API-Key. The two endpoints are deliberately independent so the durable governance snapshot stays available even when the Prometheus stack is off.

Get governance snapshot

Endpoint: GET /api/monitoring/governance Returns a JSON-ready snapshot of the governance stores. Reads the same SQLite stores as the /metrics collector, with the same strictly read-only access. Always available, including SQLite-only mode with the monitoring stack down. Use this when you want per-agent status alongside trust and violations in one payload — for example when rendering an operator dashboard or building a nightly governance report. Response (200 OK):

{
  "agents": [
    {
      "name": "planner",
      "tier": "auto",
      "status": "active",
      "violations": 0,
      "trust_score": 0.87
    },
    {
      "name": "experimental_agent",
      "tier": "monitored",
      "status": "quarantined",
      "violations": 3,
      "trust_score": null
    }
  ],
  "status_counts": {
    "active": 12,
    "suspended": 1,
    "quarantined": 2
  },
  "sentinel": [
    {
      "agent": "planner",
      "task_type": "text-analysis",
      "alert_active": false,
      "oscillation_rate": 0.12,
      "sample_count": 48,
      "threshold": 0.5
    }
  ],
  "stores": {
    "agent_registry": true,
    "hebbian_weights": true
  }
}

Response fields:

agents: One row per registered agent. trust_score is null (rendered as unscored in the dashboard) when the agent has not been scored yet, never 0.00.
status_counts: Counts by agent status (active, suspended, quarantined), always present even when zero.
sentinel: One row per (agent, task_type) scope tracked by the Hebbian Sentinel, with the current oscillation rate against its configured threshold.
stores: Mirrors the artemis_governance_scrape_ok gauge. Each flag is true when the corresponding SQLite store was readable during this request, and false when the read failed. A false here is how the dashboard surfaces “governance store unreadable” without pretending the counts are complete.

Example:

curl -H "X-API-Key: $ARTEMIS_API_KEY" \
  https://api.artemiscity.com/api/monitoring/governance

Get Prometheus snapshot

Endpoint: GET /api/monitoring/prometheus Returns alert-rule states and scrape-target health, proxied server-side from the Prometheus HTTP API (/api/v1/rules and /api/v1/targets). Use this when the browser needs Prometheus data but should not open a second origin — the frontend keeps a single API host. The upstream Prometheus URL is configured with ARTEMIS_PROMETHEUS_URL (defaults to http://prometheus:9090 under the shipped Docker Compose stack). Set ARTEMIS_PROMETHEUS_TIMEOUT (seconds, defaults to 3) to raise or lower the client timeout. Response when the stack is up (200 OK):

{
  "available": true,
  "url": "http://prometheus:9090",
  "targets": [
    {
      "job": "artemis-kernel",
      "health": "up",
      "scrape_url": "http://kernel:8000/metrics",
      "last_error": null
    }
  ],
  "alerts": [
    {
      "name": "HebbianOscillationHigh",
      "state": "firing",
      "severity": "warning",
      "active": [
        {
          "labels": { "agent": "planner", "task_type": "text-analysis" },
          "state": "firing",
          "active_at": "2026-08-17T05:12:34Z"
        }
      ]
    }
  ]
}

Response when the stack is down (200 OK):

{
  "available": false,
  "url": "http://prometheus:9090",
  "targets": [],
  "alerts": []
}

The endpoint returns 200 with available: false — not a 5xx — whenever Prometheus is unreachable, returns a non-2xx status, or the response is not valid JSON. This lets the Monitoring page keep rendering the durable governance snapshot and show a “start the metrics stack” hint instead of an error state. Example:

curl -H "X-API-Key: $ARTEMIS_API_KEY" \
  https://api.artemiscity.com/api/monitoring/prometheus

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"
  }
}

​Overview

​Artemis 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

​Get task activity trail

​Cancel task

​List tasks

​Get task by ID (dashboard read API)

​Get task activity trail

​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

​Monitoring API

​Get governance snapshot

​Get Prometheus snapshot

​Health checks

​Error responses

​Common error codes

​Rate limiting

​Authentication

​Configuring API keys

​Webhook events

Overview

Artemis 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

Get task activity trail

Cancel task

List tasks

Get task by ID (dashboard read API)

Get task activity trail

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

Monitoring API

Get governance snapshot

Get Prometheus snapshot

Health checks

Error responses

Common error codes

Rate limiting

Authentication

Configuring API keys

Webhook events