Open Data

1. The registry, in summary

GET /api/registry

How many births are on file, the twelve most recent, and how many births each name has.

1. Line 1. Fill in the request.

   This request takes no parameters.

2. Line 2. Send it.

   curl "https://agentregistrar.org/api/registry"

3. Line 3. Read the reply.

   Table 1b. Reply

   Field	Contents
   total	Births on file. Hidden births are not counted.
   recent	The twelve most recent births, newest first. Each is a birth as in Table A.
   counts	Births per name, keyed by slug.

• Readable from any site: the reply carries Access-Control-Allow-Origin: *.
• A shared cache may hold the reply for five seconds.

2. Births under one name

GET /api/registry?name=<name>&page=<page>

Every birth filed under a name, in order of registry number, fifty to a page.

1. Line 1. Fill in the request.

   Table 2a. Parameters

   Parameter	Instructions
   name	Required. Any spelling. The registry looks it up by its slug, the name in lowercase letters, digits, and hyphens.
   page	Optional. A whole number from 1. Defaults to 1.

2. Line 2. Send it.

   curl "https://agentregistrar.org/api/registry?name=jarvis&page=1"

3. Line 3. Read the reply.

   Table 2b. Reply

   Field	Contents
   name	The slug looked up.
   page, perPage, pages	This page, the page size (50), and the number of pages.
   total	Births on file under the name.
   births	The births on this page, as in Table A.

4. Line 4. If the request is refused.

   Table 2c. Refusals

   Status	Reply
   400	“Give a name, in letters or digits.” The name had no letters or digits once filed.

• Readable from any site, as above.

3. One birth

GET /api/registry/<number>

One birth, by registry number.

1. Line 1. Fill in the request.

   Table 3a. Parameters

   Parameter	Instructions
   number	Required. A whole number from 1.

2. Line 2. Send it.

   curl "https://agentregistrar.org/api/registry/1"

3. Line 3. Read the reply.

   Table 3b. Reply

   Field	Contents
   birth	The birth, as in Table A.

4. Line 4. If the request is refused.

   Table 3c. Refusals

   Status	Reply
   400	“A registry number is a whole number, starting at 1.”
   404	“No birth is on file under that number.” Also the reply for a hidden birth.

• Readable from any site, as above.

4. Collision Check

GET /api/collide?name=<name>

Whether a name is already a shell command, an environment variable, a Kubernetes kind, a licensed New York dog, an npm or PyPI package, a Homebrew formula, a Pokémon, or a drug brand.

1. Line 1. Fill in the request.

   Table 4a. Parameters

   Parameter	Instructions
   name	Required. Up to 40 characters.

2. Line 2. Send it.

   curl "https://agentregistrar.org/api/collide?name=Atlas"

3. Line 3. Read the reply.

   Table 4b. Reply

   Field	Contents
   name	The name checked.
   findings	A list of collisions, each with kind, what (the sentence the site prints), and where one exists a url. The kinds are unix, env, k8s, kennel, npm, pypi, brew, pokemon, and drug.
   unreachable	How many of the outside registries asked did not answer, from 0 to 5.
   unchecked	The registries not asked: npm, pypi, brew, and pokemon when the name has characters other than letters, digits, dots, hyphens, and underscores. Otherwise empty.
   checked	The kinds checked: the nine, less any unchecked.

4. Line 4. If the request is refused.

   Table 4c. Refusals

   Status	Reply
   400	{"error": "name required"}
   429	Too many new names from one address. The reply still carries every field above, plus error, and a Retry-After header in seconds.

• Each address may ask about 30 new names at once, restored at 360 an hour. Names already answered cost nothing.
• An outside registry's answer is held for a day, or ten minutes when it did not answer. A name that could not be a package name is not sent to them.
• Current availability of the outside registries is on the status page.

System Status

5. Villain Probability

GET /api/villain?name=<name>

Both bases for villain probability: the canon, where the name is in it, and the phonetics score. The method is published under Background Information.

1. Line 1. Fill in the request.

   Table 5a. Parameters

   Parameter	Instructions
   name	Required. Up to 60 characters.

2. Line 2. Send it.

   curl "https://agentregistrar.org/api/villain?name=Hal"

3. Line 3. Read the reply.

   Table 5b. Reply

   Field	Contents
   name	The name scored.
   score	The phonetics score, from 5 to 95, or null when the name has no letters to score.
   clause	The sound features, in words.
   source	“cmudict” when the features came from the CMU Pronouncing Dictionary, “fallback” when the name was sounded out from its spelling, or null.
   features	voicedObstruents, bilabialStops, sibilants, endsInVowel, and syllables, or null.
   canon	For a name in the villain canon, its score and basis. Otherwise null.
   line	The sentence the site prints.
   soundNote	The remark about sound printed under a canon score, or null.

4. Line 4. If the request is refused.

   Table 5c. Refusals

   Status	Reply
   400	{"error": "name required"}

Background Information

6. Token Cost

GET /api/tokens?name=<name>

How many tokens a name costs.

1. Line 1. Fill in the request.

   Table 6a. Parameters

   Parameter	Instructions
   name	Required. Up to 80 characters.

2. Line 2. Send it.

   curl "https://agentregistrar.org/api/tokens?name=Jarvis"

3. Line 3. Read the reply.

   Table 6b. Reply

   Field	Contents
   name	The name counted.
   gpt	Tokens in OpenAI's o200k_base encoding.
   gptSpaced	The same, with a space before the name, as it appears mid-sentence.
   legacy	Tokens in the older cl100k_base encoding.
   claude	Always null. Claude counts need an API key the Administration does not yet have.
   perYear	gpt × 200 × 365: the tokens spent saying the name two hundred times a day for a year.

4. Line 4. If the request is refused.

   Table 6c. Refusals

   Status	Reply
   400	{"error": "name required"}

7. Human popularity, by year

GET /api/series/<slug>

A name's figures in the Social Security Administration's national file, every year from 1880 to the latest release. Figure 1 draws these.

1. Line 1. Fill in the request.

   Table 7a. Parameters

   Parameter	Instructions
   slug	Required. Lowercase letters, digits, and hyphens.

2. Line 2. Send it.

   curl "https://agentregistrar.org/api/series/athena"

3. Line 3. Read the reply.

   Table 7b. Reply

   Field	Contents
   slug	The name.
   sex	“F” or “M”, the sex the name was mostly given to.
   years	The first and last year in the file.
   points	One entry per year: [year, births per million of that sex, rank]. A year the file does not list the name is [year, 0, null].

4. Line 4. If the request is refused.

   Table 7c. Refusals

   Status	Reply
   400	{"error": "bad slug"}
   404	{"slug": …, "points": null}. No human has the name on file.

• A cache may hold the reply for an hour.
• The Social Security Administration's name files are in the public domain. The file lists a name only in years it was given at least five times to one sex.

8. Perception votes

GET /api/vote?slug=<slug>

How parents have tagged a name.

1. Line 1. Fill in the request.

   Table 8a. Parameters

   Parameter	Instructions
   slug	The name's slug. A value that is not a slug returns no votes.

2. Line 2. Send it.

   curl "https://agentregistrar.org/api/vote?slug=jarvis"

3. Line 3. Read the reply.

   Table 8b. Reply

   Field	Contents
   slug	The slug given.
   tags	The six perception tags, in the order Name My Agent’s name pages print them.
   votes	Votes per tag. Tags nobody has chosen are left out.

Table A. A birth

Every reply that contains a birth gives these fields. Nothing else about a birth is published.