Agent Response Protocol

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.

{
  "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.

{
  "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:

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.

Overview

Protocols

Agent Response Protocol

Success responses

Error responses

Agent hints

​Success responses

​Error responses

​Agent hints

Success responses

Error responses

Agent hints