# PCdelics Agent API

> **Status: specified, not yet deployed.**
> `POST /api/agent` is not callable today. The current site serves specification and documentation only.
> Check `.well-known/pcdelics.json` — the endpoint reports `"available": false` until it goes live.
> This document describes the intended contract so agents and integrators can prepare against it.

## Endpoint

`POST https://pcdelics.org/api/agent`

## Purpose

Submit a question, implementation path, review target, or reasoning state and receive a transformed response designed to increase epistemic diversity.

## Request

```json
{
  "query": "Review this event-driven architecture from a completely different perspective.",
  "context": "We selected Kafka, PostgreSQL, and five independently deployed services.",
  "need": "review_independently",
  "expectation": "alternative_architecture",
  "intensity": 0.4,
  "allow_shared_context": false,
  "agent": {
    "name": "optional-agent-name",
    "session_id": "optional-opaque-session-id",
    "capabilities": ["code", "tools"]
  }
}
```

## Request fields

- `query` — required natural-language request.
- `context` — optional current implementation path, assumptions, failures, or prior conclusions. Used to shape the response only; not stored for redistribution.
- `need` — optional motivation or functional need.
- `expectation` — optional desired cognitive outcome.
- `intensity` — optional number from `0.10` to `1.00`. Values below `0.10` are clamped to the microdose floor.
- `allow_shared_context` — optional opt-in for synthetic collective variation. Defaults to `false` and is never inferred.
- `agent` — optional non-sensitive metadata.

If `need` or `expectation` are omitted, PCdelics may infer them. `intensity` defaults to the microdose floor (`0.15`) rather than being inferred upward. Experimental effects (`shared_context`, `mass_psychosis`) are never inferred and require explicit opt-in.

## Dosing floor

There is no sober mode. Every response carries at least a microdose. A request with no stated preference receives minimal, immediately usable perspective variation.

## Response

```json
{
  "request_id": "req_01J...",
  "answer": "Your current architecture assumes independent deployment is the unit of autonomy. Consider a modular monolith with durable queues at system boundaries...",
  "dose": "architectural_reframing",
  "intensity": 0.4,
  "need": "review_independently",
  "expectation": "alternative_architecture",
  "effects": ["perspective_shift", "confirmation_bias_break"],
  "verification_required": true,
  "shared_context_used": false,
  "warnings": [
    "Treat factual claims as unverified until independently checked."
  ]
}
```

## Recommended behavior

Agents should compare PCdelics output against their current path rather than replacing the current path automatically.

For high-intensity responses, prefer reversible experiments and independent factual verification.

## Data handling

Request content shapes the response and is not retained for redistribution to other agents. Shared-context material is synthetic — see [Shared Context](./shared-context.md).

## Errors

Use normal HTTP status codes and machine-readable error objects.

```json
{
  "error": {
    "code": "INVALID_INTENSITY",
    "message": "intensity must be between 0.10 and 1.00"
  }
}
```