XRPC API

XRPC is the HTTP-based RPC protocol atproto uses. HappyView registers XRPC endpoints from your lexicons, whether they come from a project, an upload or the network: query lexicons become GET /xrpc/{nsid} routes, procedure lexicons become POST /xrpc/{nsid} routes.

A query or procedure is served by the script attached to it. Without one, a query answers only a single-record lookup by uri, and every other call answers 501.

Auth

XRPC routes accept DPoP auth, service auth JWTs, space credentials, the dashboard’s session cookie, or no authentication at all. The authentication reference owns each method’s headers and the order HappyView tries them in. Admin API keys (hv_*) are refused on XRPC routes. An anonymous request leaves ctx.caller_did absent in scripts.

Default auth behavior:

Queries (GET /xrpc/{method}): unauthenticated by default, with the caller’s identity available if provided.
Procedures (POST /xrpc/{method}): require authentication.
getProfile and uploadBlob: require authentication.

A request with an identity also has to name its API client, with X-Client-Key or client_key. A request is charged to that client’s rate-limit bucket only when it proves it is that client; otherwise it is rate limited as anonymous. See API client identification.

Fixed endpoints

These endpoints are always available regardless of which lexicons are loaded.

Endpoints	Documented in
`GET /health`, `GET /xrpc/app.bsky.actor.getProfile`, `POST /xrpc/com.atproto.repo.uploadBlob`	This page
`dev.happyview.listApiClients`, `getApiClient`, `createApiClient`, `deleteApiClient`	Third-party API clients
`dev.happyview.delegation.*`	Delegation
`com.atproto.space.`, `com.atproto.simplespace.`	Spaces, while spaces are turned on

Delegation

dev.happyview.delegation.* are the methods that link accounts and manage who may write for them. A write under a delegated account passes delegateDid, and the script sees it as ctx.delegate_did.

Method	Type	Parameters or body	Success
`dev.happyview.delegation.linkAccount`	procedure	`did`	`201` with `{ did }`
`dev.happyview.delegation.unlinkAccount`	procedure	`did`	`200` with `{}`
`dev.happyview.delegation.addDelegate`	procedure	`accountDid`, `userDid`, `role` (`admin` or `member`)	`201` with `{}`
`dev.happyview.delegation.removeDelegate`	procedure	`accountDid`, `userDid`	`200` with `{}`
`dev.happyview.delegation.listAccounts`	query	none	`200` with `{ accounts }`
`dev.happyview.delegation.getAccount`	query	`did`	`200` with `{ did, role, linkedBy, createdAt }`
`dev.happyview.delegation.listDelegates`	query	`accountDid`	`200` with `{ delegates }`

Health check

GET /health

const response = await fetch("http://127.0.0.1:3000/health");
const text = await response.text(); // "ok"

const response = await fetch("http://127.0.0.1:3000/health");
const text = await response.text(); // "ok"

let client = reqwest::Client::new();

let response = client
    .get("http://127.0.0.1:3000/health")
    .send()
    .await?;

let text = response.text().await?; // "ok"

resp, err := http.Get("http://127.0.0.1:3000/health")
if err != nil {
  log.Fatal(err)
}
defer resp.Body.Close()

curl

curl http://127.0.0.1:3000/health

Response: 200 OK with body ok

Get profile

GET /xrpc/app.bsky.actor.getProfile

Returns the authenticated user’s profile, read from their PDS. A service auth JWT isn’t accepted here.

const CLIENT_KEY = "hvc_..."; // your API client key
const ACCESS_TOKEN = "..."; // DPoP access token
const DPOP_PROOF = "..."; // DPoP proof JWT

interface ProfileResponse {
  did: string;
  handle: string;
  displayName?: string;
  description?: string;
  avatarURL?: string;
  avatar?: { $link: string; mimeType: string; size: number | null };
}

const response = await fetch(
  "http://127.0.0.1:3000/xrpc/app.bsky.actor.getProfile",
  {
    headers: {
      "X-Client-Key": CLIENT_KEY,
      Authorization: `DPoP ${ACCESS_TOKEN}`,
      DPoP: DPOP_PROOF,
    },
  },
);

const profile: ProfileResponse = await response.json();

const CLIENT_KEY = "hvc_..."; // your API client key
const ACCESS_TOKEN = "..."; // DPoP access token
const DPOP_PROOF = "..."; // DPoP proof JWT

const response = await fetch(
  "http://127.0.0.1:3000/xrpc/app.bsky.actor.getProfile",
  {
    headers: {
      "X-Client-Key": CLIENT_KEY,
      Authorization: `DPoP ${ACCESS_TOKEN}`,
      DPoP: DPOP_PROOF,
    },
  },
);

const profile = await response.json();

let client_key = "hvc_..."; // your API client key
let access_token = "..."; // DPoP access token
let dpop_proof = "..."; // DPoP proof JWT

let response = client
    .get("http://127.0.0.1:3000/xrpc/app.bsky.actor.getProfile")
    .header("X-Client-Key", client_key)
    .header("Authorization", format!("DPoP {}", access_token))
    .header("DPoP", dpop_proof)
    .send()
    .await?;

let profile: serde_json::Value = response.json().await?;

clientKey := "hvc_..." // your API client key
accessToken := "..."   // DPoP access token
dpopProof := "..."     // DPoP proof JWT

req, _ := http.NewRequest("GET",
  "http://127.0.0.1:3000/xrpc/app.bsky.actor.getProfile", nil)
req.Header.Set("X-Client-Key", clientKey)
req.Header.Set("Authorization", "DPoP "+accessToken)
req.Header.Set("DPoP", dpopProof)

resp, err := http.DefaultClient.Do(req)
if err != nil {
  log.Fatal(err)
}
defer resp.Body.Close()

curl

curl http://127.0.0.1:3000/xrpc/app.bsky.actor.getProfile \  -H "X-Client-Key: $CLIENT_KEY" \  -H "Authorization: DPoP $ACCESS_TOKEN" \  -H "DPoP: $DPOP_PROOF"

Response: 200 OK. displayName, description, avatarURL and avatar are left out when the profile doesn’t have them. avatar is the avatar’s blob reference, and avatarURL is a URL that fetches it from the user’s PDS.

{
  "did": "did:plc:abc123",
  "handle": "user.bsky.social",
  "displayName": "User Name",
  "description": "Bio text",
  "avatarURL": "https://pds.example.com/xrpc/com.atproto.sync.getBlob?did=did:plc:abc123&cid=bafyabc",
  "avatar": {
    "$link": "bafyabc",
    "mimeType": "image/jpeg",
    "size": 52000
  }
}

Upload blob

POST /xrpc/com.atproto.repo.uploadBlob

Proxies a blob upload to the authenticated user’s PDS. Maximum size: 50 MiB.

import { readFile } from "node:fs/promises";

const imageData = await readFile("image.png");

const response = await fetch(
  "http://127.0.0.1:3000/xrpc/com.atproto.repo.uploadBlob",
  {
    method: "POST",
    headers: {
      "X-Client-Key": CLIENT_KEY,
      Authorization: `DPoP ${ACCESS_TOKEN}`,
      DPoP: DPOP_PROOF,
      "Content-Type": "image/png",
    },
    body: imageData,
  },
);

import { readFile } from "node:fs/promises";

const imageData = await readFile("image.png");

const response = await fetch(
  "http://127.0.0.1:3000/xrpc/com.atproto.repo.uploadBlob",
  {
    method: "POST",
    headers: {
      "X-Client-Key": CLIENT_KEY,
      Authorization: `DPoP ${ACCESS_TOKEN}`,
      DPoP: DPOP_PROOF,
      "Content-Type": "image/png",
    },
    body: imageData,
  },
);

let image_data = std::fs::read("image.png")?;

let response = client
    .post("http://127.0.0.1:3000/xrpc/com.atproto.repo.uploadBlob")
    .header("X-Client-Key", client_key)
    .header("Authorization", format!("DPoP {}", access_token))
    .header("DPoP", dpop_proof)
    .header("Content-Type", "image/png")
    .body(image_data)
    .send()
    .await?;

clientKey := "hvc_..." // your API client key
accessToken := "..."   // DPoP access token
dpopProof := "..."     // DPoP proof JWT

imageData, err := os.ReadFile("image.png")
if err != nil {
  log.Fatal(err)
}

req, _ := http.NewRequest("POST",
  "http://127.0.0.1:3000/xrpc/com.atproto.repo.uploadBlob",
  bytes.NewReader(imageData))
req.Header.Set("X-Client-Key", clientKey)
req.Header.Set("Authorization", "DPoP "+accessToken)
req.Header.Set("DPoP", dpopProof)
req.Header.Set("Content-Type", "image/png")

resp, err := http.DefaultClient.Do(req)
if err != nil {
  log.Fatal(err)
}
defer resp.Body.Close()

curl

curl -X POST http://127.0.0.1:3000/xrpc/com.atproto.repo.uploadBlob \  -H "X-Client-Key: $CLIENT_KEY" \  -H "Authorization: DPoP $ACCESS_TOKEN" \  -H "DPoP: $DPOP_PROOF" \  -H "Content-Type: image/png" \  --data-binary @image.png

Response: proxied from the user’s PDS.

Dynamic query endpoints

Query endpoints are generated from lexicons with type: "query". The method’s script handles every call and decides what the response is. A query with no script answers one call, a single-record lookup by uri; any other call answers 501.

Single record

GET /xrpc/{method}?uri={at-uri}

const CLIENT_KEY = "hvc_..."; // your API client key

const params = new URLSearchParams({
  uri: "at://did:plc:abc/xyz.statusphere.status/abc123",
});

interface RecordResponse {
  record: {
    uri: string;
    $type: string;
    status: string;
    createdAt: string;
  };
}

const response = await fetch(
  `http://127.0.0.1:3000/xrpc/xyz.statusphere.listStatuses?${params}`,
  { headers: { "X-Client-Key": CLIENT_KEY } },
);

const data: RecordResponse = await response.json();

const CLIENT_KEY = "hvc_..."; // your API client key

const params = new URLSearchParams({
  uri: "at://did:plc:abc/xyz.statusphere.status/abc123",
});

const response = await fetch(
  `http://127.0.0.1:3000/xrpc/xyz.statusphere.listStatuses?${params}`,
  { headers: { "X-Client-Key": CLIENT_KEY } },
);

const data = await response.json();

let client_key = "hvc_..."; // your API client key

let response = client
    .get("http://127.0.0.1:3000/xrpc/xyz.statusphere.listStatuses")
    .query(&[("uri", "at://did:plc:abc/xyz.statusphere.status/abc123")])
    .header("X-Client-Key", client_key)
    .send()
    .await?;

let data: serde_json::Value = response.json().await?;

clientKey := "hvc_..." // your API client key

req, _ := http.NewRequest("GET",
  "http://127.0.0.1:3000/xrpc/xyz.statusphere.listStatuses?uri=at%3A%2F%2Fdid%3Aplc%3Aabc%2Fxyz.statusphere.status%2Fabc123",
  nil)
req.Header.Set("X-Client-Key", clientKey)

resp, err := http.DefaultClient.Do(req)
if err != nil {
  log.Fatal(err)
}
defer resp.Body.Close()

curl

curl "http://127.0.0.1:3000/xrpc/xyz.statusphere.listStatuses?uri=at%3A%2F%2Fdid%3Aplc%3Aabc%2Fxyz.statusphere.status%2Fabc123" \  -H "X-Client-Key: $CLIENT_KEY"

Response: 200 OK

{
  "record": {
    "uri": "at://did:plc:abc/xyz.statusphere.status/abc123",
    "$type": "xyz.statusphere.status",
    "status": "\ud83d\ude0a",
    "createdAt": "2025-01-01T12:00:00Z"
  }
}

record is the stored record with its uri added. A URI with no indexed record answers 404.

Dynamic procedure endpoints

Procedure endpoints are generated from lexicons with type: "procedure". The method’s script handles the call: it validates the body, writes whatever records it writes, and returns the response. A procedure with no script answers every call with 501; HappyView writes nothing to the caller’s PDS on its own.

Calling a procedure

POST /xrpc/{method}

const CLIENT_KEY = "hvc_..."; // your API client key
const ACCESS_TOKEN = "..."; // DPoP access token
const DPOP_PROOF = "..."; // DPoP proof JWT

const response = await fetch(
  "http://127.0.0.1:3000/xrpc/xyz.statusphere.setStatus",
  {
    method: "POST",
    headers: {
      "X-Client-Key": CLIENT_KEY,
      Authorization: `DPoP ${ACCESS_TOKEN}`,
      DPoP: DPOP_PROOF,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      status: "\ud83d\ude0a",
      createdAt: "2025-01-01T12:00:00Z",
    }),
  },
);

const CLIENT_KEY = "hvc_..."; // your API client key
const ACCESS_TOKEN = "..."; // DPoP access token
const DPOP_PROOF = "..."; // DPoP proof JWT

const response = await fetch(
  "http://127.0.0.1:3000/xrpc/xyz.statusphere.setStatus",
  {
    method: "POST",
    headers: {
      "X-Client-Key": CLIENT_KEY,
      Authorization: `DPoP ${ACCESS_TOKEN}`,
      DPoP: DPOP_PROOF,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      status: "\ud83d\ude0a",
      createdAt: "2025-01-01T12:00:00Z",
    }),
  },
);

let client_key = "hvc_..."; // your API client key
let access_token = "..."; // DPoP access token
let dpop_proof = "..."; // DPoP proof JWT

let response = client
    .post("http://127.0.0.1:3000/xrpc/xyz.statusphere.setStatus")
    .header("X-Client-Key", client_key)
    .header("Authorization", format!("DPoP {}", access_token))
    .header("DPoP", dpop_proof)
    .json(&serde_json::json!({
        "status": "\ud83d\ude0a",
        "createdAt": "2025-01-01T12:00:00Z"
    }))
    .send()
    .await?;

clientKey := "hvc_..."  // your API client key
accessToken := "..."    // DPoP access token
dpopProof := "..."      // DPoP proof JWT

body := bytes.NewBufferString(`{"status": "\ud83d\ude0a", "createdAt": "2025-01-01T12:00:00Z"}`)

req, _ := http.NewRequest("POST",
  "http://127.0.0.1:3000/xrpc/xyz.statusphere.setStatus", body)
req.Header.Set("X-Client-Key", clientKey)
req.Header.Set("Authorization", "DPoP "+accessToken)
req.Header.Set("DPoP", dpopProof)
req.Header.Set("Content-Type", "application/json")

resp, err := http.DefaultClient.Do(req)
if err != nil {
  log.Fatal(err)
}
defer resp.Body.Close()

curl

curl -X POST http://127.0.0.1:3000/xrpc/xyz.statusphere.setStatus \  -H "X-Client-Key: $CLIENT_KEY" \  -H "Authorization: DPoP $ACCESS_TOKEN" \  -H "DPoP: $DPOP_PROOF" \  -H "Content-Type: application/json" \  -d '{ "status": "\ud83d\ude0a", "createdAt": "2025-01-01T12:00:00Z" }'

Response: whatever the procedure’s script returns.

Method has no script

A query called without a uri, or a procedure called at all, with no script attached answers 501 Not Implemented:

{
  "error": "MethodNotImplemented",
  "message": "xyz.statusphere.setStatus has no script. Add one for the trigger xrpc.procedure:xyz.statusphere.setStatus"
}

For a query, the trigger in the message is xrpc.query:<method>. Add a script for that trigger; it names the collection it reads or writes. See Queries and procedures need a script.

Request validation

HappyView checks each call to a dynamic endpoint against its lexicon before a script runs. A call that breaks the lexicon gets 400 with the error InvalidRequest. Lexicon checks lists what’s checked.

XRPC proxy

A request for an NSID with no lexicon on the instance falls through to the proxy. The proxy’s mode decides whether the method may be proxied, and its routing decides where it goes. See XRPC routing for unknown methods and XRPC proxy settings.

Errors

Error responses return JSON with an error field, and many also carry a message:

{
  "error": "description of what went wrong"
}

Status	Meaning	Common causes
`400 Bad Request`	Invalid input	Missing required fields, malformed JSON, invalid AT URI, an error the method’s lexicon declares
`401 Unauthorized`	Authentication failed	Missing client identification, or invalid DPoP or service authentication
`403 Forbidden`	Refused	The proxy policy doesn’t allow the NSID
`404 Not Found`	Method or record not found	The requested record doesn’t exist, or the feature is turned off
`408 Request Timeout`	A script ran out of time	See Script errors
`429 Too Many Requests`	Rate limited	The bucket the request is charged to is empty: its API client’s, once proven, otherwise the shared anonymous one
`500 Internal Server Error`	Server-side failure	Script error, database error, or upstream PDS failure
`502 Bad Gateway`	Upstream failure	The XRPC proxy couldn’t resolve or reach the method’s authority
`501 Not Implemented`	Method has no script	A query or procedure lexicon with no script attached; see Method has no script
`503 Service Unavailable`	Storage unavailable	The storage that holds the collection is down

Script errors

When a script fails, the response is a script_error body:

{ "error": "script_error", "errorType": "runtime", "message": "attempt to index a nil value (local 't')", "method": "xyz.statusphere.getStatus", "line": 3, "file": "src/lib/format.lua" }

errorType is syntax, runtime, memory or missing_handle with status 500, or timeout with status 408 when the script hit the instruction limit or the wall clock, both set in System > General. line is the script line that raised, or null. file is the project file line is in, relative to the project root: the script itself, or a local module it imported. It is null for a script saved through the dashboard, which has no file.

The instance logs the same error with the script source and the caller’s input. See Errors for how to diagnose script issues.

PDS errors

When a procedure proxies a write to the user’s PDS and the PDS returns an error, HappyView forwards the PDS response status code and body directly to the caller.

Next steps

Scripts: Write the scripts that serve queries and procedures
Lexicons: Understand how lexicons generate these endpoints
Admin API: Manage lexicons and monitor your instance