# API Documentation

## Agent State

### Overview

Agent State provides short-term, task-scoped storage for agentic workflows. Unlike memories (long-term facts), state tracks the agent's current working context: task progress, pending actions, and session variables.

**Use cases:** Multi-step task automation, workflow position tracking, pending tool call results, session variables, and resumable conversations.

### PUT /state/:key

Create or update agent state for a given key.

#### Required Headers
- `X-Subject-ID`: Subject/user identifier
- `value`: JSON state to store (required)
- `ttl_seconds`: Time-to-live in seconds (optional)

```bash
curl -X PUT "https://www.mnexium.com/api/v1/state/current_task" \
  -H "x-mnexium-key: $MNX_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Subject-ID: user_123" \
  -d '{\n    "value": {\n      "status": "in_progress",\n      "task": "Plan trip to Tokyo",\n      "steps_completed": ["research", "book_flights"],\n      "next_step": "book_hotels"\n    },\n    "ttl_seconds": 3600\n  }'
```

### GET /state/:key

Retrieve agent state for a given key.

#### Required Headers
- `X-Subject-ID`: Subject/user identifier

```bash
curl "https://www.mnexium.com/api/v1/state/current_task" \
  -H "x-mnexium-key: $MNX_KEY" \
  -H "X-Subject-ID: user_123"
```

#### Example Response
```json
{
  "key": "current_task",
  "value": {
    "status": "in_progress",
    "task": "Plan trip to Tokyo",
    "next_step": "book_hotels"
  },
  "ttl": "2025-01-01T12:00:00Z",
  "updated_at": "2025-01-01T11:00:00Z"
}
```

### DELETE /state/:key

Delete agent state (soft delete via TTL expiration).

#### Required Headers
- `X-Subject-ID`: Subject/user identifier

### State Injection in Proxy

Load and inject agent state into LLM context via the `mnx.state` config:

```bash
curl -X POST "https://www.mnexium.com/api/v1/chat/completions" \
  -H "x-mnexium-key: $MNX_KEY" \
  -H "x-openai-key: $OPENAI_KEY" \
  -d '{\n    "model": "gpt-4o-mini",\n    "messages": [{ "role": "user", "content": "What should I do next?" }],\n    "mnx": {\n      "subject_id": "user_123",\n      "state": {\n        "load": true,\n        "key": "current_task"\n      }\n    }  }
```

When `state.load: true`, the agent's current state is injected as a system message, allowing the LLM to resume tasks and avoid repeating completed work.

### Key Naming Conventions

Recommended patterns for state keys:
- `current_task`: Default key for general task state
- `task:onboarding`: Named workflow state
- `tool:weather:tc_123`: Pending tool call result
- `flow:checkout`: Multi-step flow position