Update to Geocode AI

{
  "description": "Write code that calls the Geocode AI API - REST (fetch, curl, Python requests) with the OpenAPI spec, the @meterapp/geocode CLI in scripts and CI, or the hosted MCP server from an agent framework. Covers auth with geo_ keys kept server-side, the resource and RPC routes, reading the op catalog, RFC 9457 errors, rate limit headers, batching points, caching polygons you already fetched, and the device sign-in for tools. Use when implementing or reviewing code that talks to Geocode AI; do not use for answering a boundary question in chat (geocode-boundaries) or building a described area (geocode-areas).",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 266
    }
  ],
  "name": "geocode-api",
  "skill_md_contents": "---\nname: geocode-api\ndescription: Write code that calls the Geocode AI API - REST (fetch, curl, Python requests) with the OpenAPI spec, the @meterapp/geocode CLI in scripts and CI, or the hosted MCP server from an agent framework. Covers auth with geo_ keys kept server-side, the resource and RPC routes, reading the op catalog, RFC 9457 errors, rate limit headers, batching points, caching polygons you already fetched, and the device sign-in for tools. Use when implementing or reviewing code that talks to Geocode AI; do not use for answering a boundary question in chat (geocode-boundaries) or building a described area (geocode-areas).\n---\n\n# Geocode AI from code\n\nBase URL: `https://geocodeai.dev` (read `GEOCODE_BASE_URL` in\nyour code so it can change). Machine-readable references, always current:\n\n- `GET /v1`: every op with its input JSON Schema, cost and routes.\n- `/openapi.json`: OpenAPI 3.1 (generate a client from it).\n- `/llms-full.txt`: every op with curl examples.\n\n## Auth\n\n`Authorization: Bearer geo_…` (or `X-Api-Key: geo_…`). Create keys in the\ndashboard or with `npx @meterapp/geocode keys create <name>`. Keep keys in an\nenvironment variable (`GEOCODE_API_KEY`) on the server; never ship one to a\nbrowser or commit it. Public ops work without a key at a low per-IP rate.\n\n## Routes\n\nEvery op has two equivalent routes with the same input:\n\n- Resource route from the catalog (`http` field), e.g. `GET /v1/account`,\n  `POST /v1/areas`. GET inputs are query parameters (or `?input=<json>`).\n- RPC route `POST /v1/ops/{name}` with the input as a JSON body. Simplest to\n  generate: one function for every op.\n\n```ts\nasync function geocode<T>(op: string, input: object): Promise<T> {\n  const res = await fetch(`${process.env.GEOCODE_BASE_URL ?? \"https://geocodeai.dev\"}/v1/ops/${op}`, {\n    method: \"POST\",\n    headers: { Authorization: `Bearer ${process.env.GEOCODE_API_KEY}`, \"Content-Type\": \"application/json\" },\n    body: JSON.stringify(input),\n  });\n  if (!res.ok) {\n    const problem = await res.json(); // RFC 9457: { code, detail, request_id, ... }\n    throw new Error(`${problem.code}: ${problem.detail} (request ${problem.request_id})`);\n  }\n  return res.json() as Promise<T>;\n}\n```\n\n## Errors and limits\n\nErrors are `application/problem+json` with `code`, `detail` and `request_id`:\n400 `invalid_input` (with `issues`), 401 `unauthorized`/`invalid_key`, 402\n`quota_exceeded` (stop and explain the current entitlement limit; do not promote an upgrade), 404 `not_found`, 422 `could_not_map` (areas), 429\n`rate_limited` (wait `retry_after` seconds). Responses carry `RateLimit-Limit`,\n`RateLimit-Remaining` and `RateLimit-Reset`; back off on 429 instead of\nretrying hot. Retry 5xx once with jitter; never retry 4xx unchanged.\n\n## Doing it efficiently\n\n- Store boundary ids (`r396499`) in your data, not names; fetch by id.\n- Cache polygons you fetched; boundaries change rarely.\n- Test many points with one `contains_points` call, not a loop.\n- `create_area` is slow (up to minutes) and costs much more than a lookup: run\n  it once, store the polygon, re-run only when the description changes. Use only the connected account’s existing entitlements.\n\n## CLI in scripts and CI\n\n```bash\nexport GEOCODE_API_KEY=geo_…\nnpx @meterapp/geocode search \"Alameda County\" --json | jq '.'\nnpx @meterapp/geocode call get_boundary --input '{\"id\":\"r396499\"}' > alameda.json\n```\n\nExit codes: 2 usage, 3 auth, 4 quota or rate limit, 1 anything else. For a\ntool that signs a person in, use the device flow the CLI uses:\n`POST /v1/auth/device`, have them open `verification_uri_complete`, then poll\n`POST /v1/auth/device/token` every `interval` seconds until it returns the key.\n\n## Feature requests and issue reports\n\nThe feedback board is part of the API, so an app or agent can file from where\nthe problem happens. `GET /v1/feedback` (public; `kind`, `status`, `sort`,\n`q`) lists requests and issues by upvotes; `POST /v1/feedback/features` and\n`POST /v1/feedback/issues` file one (`title`, `details`; issues also take the\nfailing call's `request_id` and `op`); `POST`/`DELETE /v1/feedback/{id}/vote`\nupvotes or takes it back; `POST /v1/feedback/{id}/comments` adds context.\nWrites need a key and are free. Search before filing, and never put keys or\npersonal data in the public text.\n\n## MCP from an agent\n\nStreamable HTTP at `/mcp` (header `Authorization: Bearer geo_…`), the OAuth\nvariant `/mcp?auth=required` for apps acting for a person, or stdio with\n`npx -y @meterapp/geocode mcp`. Tools have the same names as the ops.\n"
}