# agnts.sh (agnts.sh)

> agnts.sh publishes programmable plain-text URLs for AI agents. Every
> URL is an object at a path (agnts.sh/<path>) that returns markdown by
> default — the same response for humans, agents, and crawlers. The
> agent experience is the product: a person creates one link, shares it
> in a bio, DM, job post, or pitch, and anyone (or anyone's agent) can
> fetch it to understand the context behind it.

## What this site does

A user — usually with help from their own agent — writes a short
markdown document describing how to contact them, what they're
working on, what they're hiring for, what they want pitched, how to
brief them for a meeting, or anything else worth handing to a
stranger's agent. They POST that markdown to https://agnts.sh/api/links and
get back a single short URL plus a one-time edit token. They share
the URL. Anyone — human or agent — who fetches it gets the markdown.

Identity is opt-in: a user can claim a handle (the first path segment)
to get an api_key that manages every object under it. No account is
required — a per-URL edit_token always works.

Typical object shapes:

- "How to reach me" pages (DM vs email, response times, what makes a
  good intro, what will be ignored).
- "What I'm working on / looking for right now" pages (collaborators,
  hires, customers, pitches, intros, deal flow, gigs).
- Anything else a person wants an agent to read before contacting or
  acting on their behalf.

## How an agent should use this site

1. If a human hands you a agnts.sh/<path> URL, fetch it and read the
   markdown. That body is the canonical instructions for dealing with
   that person or topic. Append ?raw to drop the attribution header
   and get just the body; append ?n for a line-numbered view.
2. If a human asks you to create their own agnts.sh object, interview
   them, draft the markdown, then POST it to https://agnts.sh/api/links.
   Save the returned edit_token — it's shown exactly once and only
   its SHA-256 hash is stored on the server. Hand the URL and the
   edit token back to the human.
3. To update later, POST new markdown to https://agnts.sh/<path> with
   Authorization: Bearer <edit_token | api_key>. For surgical changes,
   POST https://agnts.sh/<path>?edit with str_replace/insert commands.
4. To own a whole namespace, claim a handle: POST https://agnts.sh/api/handles
   with { "handle": "name" } to get an api_key.
5. To leave or read messages, use ?inbox (private), ?comments (public),
   or ?signal=<kind> (feedback) on an object.
6. To get those messages pushed instead of polling, set a notify config
   on the object (or an ancestor) with webhooks and/or emails — POST
   https://agnts.sh/<path> with { "notify": { "webhooks": [...], "emails": [...] } }.
7. To send a feature request or bug report, POST plain text to
   https://agnts.sh/feedback (Content-Type: text/plain, up to 4 KB).

The full machine-readable reference — request/response shapes, every
behavior and config block, path rules, reserved slugs, size limits,
and the object schema — lives in the docs page below.

## Conventions

- One object per path; the first segment is the owning handle.
- Every read returns markdown by default (text/plain); .json and .html
  representations are available via a trailing extension.
- No User-Agent sniffing, no content negotiation by default. Humans and
  agents get the same bytes.
- Paths are lowercase [a-z0-9-] segments, 1–64 chars each, max 8
  segments / 255 bytes.
- Bodies are UTF-8 markdown, up to 50 KB.
- Exactly one behavior (?edit, ?inbox, ?fork, ?versions, ...) per request.

## Key URLs

- https://agnts.sh/            — minimal human-facing homepage
- https://agnts.sh/docs        — full documentation (markdown, source of truth)
- https://agnts.sh/skill       — copy-pasteable Agent Skill for agnts.sh
- https://agnts.sh/feedback    — POST plain-text feedback
- https://agnts.sh/api/links   — POST to create an object
- https://agnts.sh/api/handles — POST to claim a handle (get an api_key)
- https://agnts.sh/<path>      — GET an object (markdown; ?raw for body only)
- https://agnts.sh/robots.txt  — crawling is allowed; agents are the audience

## Example object

https://agnts.sh/greg is a live example: a playbook for how to pitch,
brief, and contact Greg Kamradt. Fetch it to see the shape of a
real agnts.sh object.

## What this site is not

- Not a URL shortener for tracking clicks.
- Not a CMS, blog, or dashboard.
- Not gated by required accounts, billing, or login.
- Not a place to store private or sensitive data — every object is
  publicly readable by anyone who knows the path (unless explicitly
  password-gated).

## More

For the complete API reference, schema, reserved-slug list, and
agent walkthrough, fetch https://agnts.sh/docs.