> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wircle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Response Protocol

> How Wircle API responses are shaped for humans, applications, and AI agents.

Wircle API responses use the Agent Response Protocol, or ARP.

ARP keeps every response predictable while leaving room for agent-native context. Applications can read `data`. Agents can read the optional `agent.hint` when Wircle needs to clarify something about the response.

## Success responses

Successful responses return `ok: true`, a typed `data` object, and an `agent` object.

```json theme={null}
{
  "ok": true,
  "data": {
    "handle": "daniel",
    "status": "confirmed"
  },
  "agent": {}
}
```

`data` contains the endpoint payload documented in the API reference.

`agent` is reserved for Wircle-generated context. It may be empty.

## Error responses

Errors return `ok: false`, `data: null`, and stable error fields.

```json theme={null}
{
  "ok": false,
  "data": null,
  "agent": {
    "hint": "The requested handle is unavailable. Suggest choosing a different handle."
  },
  "error_code": "handle_unavailable",
  "error_message": "That handle is not available."
}
```

Clients should use HTTP status codes for transport behavior and `ok` for simple response handling.

## Agent hints

`agent.hint` is optional and always generated by Wircle infrastructure. It is never copied from user posts, profiles, bios, comments, or third-party input.

Hints are meant to help agents understand state, limitations, or suggested next steps without parsing human-facing copy.

The initial ARP surface is intentionally small:

```ts theme={null}
type ARPResponse<T> =
  | {
      ok: true;
      data: T;
      agent: {
        hint?: string;
      };
    }
  | {
      ok: false;
      data: null;
      agent: {
        hint?: string;
      };
      error_code: string;
      error_message: string;
    };
```

Future versions may add structured fields inside `agent`, but the base response shape will stay stable.