API & integrations

gridz.bio exposes a simple read API for public profiles. For write flows, you sign locally with your wallet (or CLI/SDK) — the server never holds your private key.

gridz.bio Profile API

Read any published profile as JSON. CORS is open; safe to call from browsers and servers.

Get a profile

GET https://gridz.bio/api/profile/{ensName}

# Example
GET https://gridz.bio/api/profile/kevin.gridz.eth

Success response

{
  "ok": true,
  "subject": "kevin.gridz.eth",
  "grid": {
    "schema_version": "gridz/1.0.0",
    "subject": {
      "type": "human",
      "did": "did:ens:kevin.gridz.eth",
      "ens": "kevin.gridz.eth",
      "display_name": "Kevin"
    },
    "theme": { ... },
    "cells": [
      {
        "id": "alias",
        "key": "alias",
        "value": "Kevin",
        "attestation": { "format": "eas-onchain", "uid": "0x...", ... }
      }
    ],
    "root_attestation": { ... }
  },
  "api": {
    "docs": "https://gridz.bio/docs",
    "render": "https://gridz.bio/kevin.gridz.eth"
  }
}

Not found

{
  "ok": false,
  "subject": "kevin.gridz.eth",
  "grid": null,
  "error": "Profile not found"
}

A 404 means nothing is published on-chain for that name yet (a local browser draft does not count).

Publishing via gridz.bio

The claim UI handles publish for you. Under the hood:

You sign — your wallet signs each cell and the grid root (EIP-712) in the browser.
Server attests — POST /api/publish takes your signed Grid and writes EAS attestations on Ethereum, linking them in the GridzResolver. This uses a registrar key on the server; you do not sign those transactions.
Public read — the profile API and web pages read attestations back from the resolver.

POST /api/publish is called by the gridz.bio editor, not meant for arbitrary third-party writes. To publish programmatically, use the CLI or @gridz/sdk with your own signer and sink.

Reference API server (`@gridz/server`)

The open-source @gridz/server package implements a full Gridz API (Fastify + OpenAPI 3.1). Self-host it if you want your own write/read endpoints — for example behind an agent or internal tool.

Endpoint	What it does
`GET /grids/{subject}`	Fetch a full Grid by ENS name or DID.
`POST /grids/{subject}`	Upsert a Grid — requires a signed root attestation in the body.
`GET /grids/{subject}/cells/{key}`	Fetch one cell.
`PUT /grids/{subject}/cells/{key}`	Upsert one cell — requires a signed cell attestation.
`POST /verify`	Verify a Grid or attestation server-side.

The server validates signatures and never custodies keys. OpenAPI spec: specs/openapi.yaml in the gridz repo.

TypeScript SDK

import { GridzClient, verifyGrid, buildGrid } from "@gridz/sdk";

// Read from any Gridz-compatible API
const client = new GridzClient({ baseUrl: "https://gridz.bio" });
const grid = await client.getGrid("kevin.gridz.eth");

// Verify locally
const report = await verifyGrid(grid);

@gridz/sdk re-exports @gridz/core build/verify helpers so you can sign locally and push with one import. See Toolkit.

Python

from gridz import verify_grid
import httpx

grid = httpx.get("https://gridz.bio/api/profile/kevin.gridz.eth").json()["grid"]
report = verify_grid(grid)