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

# API Reference

> Reference for Artemis City's Agent API, Agent Transmission Protocol (ATP) message format, action types, and admin system endpoints.

## Overview

Artemis City exposes three primary API surfaces:

1. **Agent API**: Task submission and execution
2. **ATP (Agent Transmission Protocol)**: Structured inter-agent messaging
3. **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

```text theme={null}
#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

```text theme={null}
#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)

```text theme={null}
#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

```text theme={null}
#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

```text theme={null}
#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:**

```json theme={null}
{
  "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):**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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):**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

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

**Response:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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):**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "alignment_score": 0.85,
  "accuracy_score": 0.92,
  "efficiency_score": 0.88
}
```

**Response:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "override_tier": "monitored",
  "rationale": "Manual review confirms safe behavior"
}
```

**Response:**

```json theme={null}
{
  "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):**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "approved_by": "admin_uuid",
  "rationale": "Code review passed, all tests green",
  "override_risk": false
}
```

**Response:**

```json theme={null}
{
  "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:**

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

**Response:**

```json theme={null}
{
  "update_id": "uuid",
  "status": "rejected",
  "rejected_at": "2026-02-21T10:35:00Z"
}
```

### Propose Rollback

**Endpoint:** `POST /api/v1/governance/rollbacks`

**Request:**

```json theme={null}
{
  "checkpoint_id": "uuid",
  "initiated_by": "admin_uuid",
  "reason": "error_detected",
  "details": "Anomaly: error rate > 5%"
}
```

**Response (202 Accepted):**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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](#agent-transmission-protocol-atp) 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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "message": {
    "header": { "mode": "direct", "context": "...", "actionType": "execute", "targetZone": "kernel" },
    "payload": { "content": "..." }
  }
}
```

**Response:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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](/Documentation/memory/hybrid-memory-bus) or the semantic search endpoints.

**Request:**

```json theme={null}
{
  "text": "Find tasks related to data processing",
  "model": "text-embedding-3-small"
}
```

**Response:**

```json theme={null}
{
  "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]`.

```text theme={null}
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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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](/Documentation/governance/trust-scoring) 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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "amount": 0.02
}
```

**Response:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "operation": "delete"
}
```

**Response:**

```json theme={null}
{
  "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:**

```json theme={null}
{
  "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](/Documentation/memory/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:**

```json theme={null}
{
  "agent1": "planner-uuid",
  "agent2": "summarizer-uuid",
  "delta": 0.05
}
```

**Response:**

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```text theme={null}
Authorization: Bearer <api_key>
```

```text theme={null}
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:

```bash theme={null}
ARTEMIS_API_KEY_<NAME>=<key>:<role>:<perm1,perm2,...>
```

For example:

```bash theme={null}
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`:

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

Event payload:

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


## Related topics

- [Changelog](/Changelog/changelog.md)
- [Trust scoring and access levels](/Documentation/governance/trust-scoring.md)
- [Working with ATP messages](/Documentation/architecture/atp-protocol.md)
- [Secrets and environment setup](/Documentation/operations/secrets-setup.md)
- [Project structure](/Documentation/operations/project-structure.md)