{ "openapi": "3.1.0", "info": { "title": "Negirau Public API", "description": "Read-only, anonymous, CORS-open API for building third-party viewers over Negirau data. Counts are only ever exposed as buckets (anti-ranking discipline).", "version": "0.1.0" }, "servers": [ { "url": "https://api.negirau.com/v1" } ], "paths": { "/subjects": { "get": { "operationId": "listSubjects", "summary": "List and search subjects", "description": "Cursor-paginated subject listing. `q` does free-text name search (substring, Japanese and English); category/kind/region/date filters compose with it. With `near`, switches to a distance-ordered search over subjects that have a spatial dimension (no cursor; results truncated at `limit`).", "x-mcp-tool-name": "negirau_list_subjects", "x-agent-description": "Search Negirau subjects (facilities, events, services that receive appreciation). Use q for name search, near='lat,lng' for proximity search.", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Free-text name search (substring match, Japanese and English; minimum 3 characters)", "schema": { "description": "Free-text name search (substring match, Japanese and English; minimum 3 characters)", "type": "string", "minLength": 3, "maxLength": 100 } }, { "name": "category", "in": "query", "required": false, "description": "Filter by category", "schema": { "description": "Filter by category", "type": "string" } }, { "name": "kind", "in": "query", "required": false, "description": "Filter by kind", "schema": { "description": "Filter by kind", "type": "string" } }, { "name": "region", "in": "query", "required": false, "description": "Regional code (JP: JIS X 0402)", "schema": { "description": "Regional code (JP: JIS X 0402)", "type": "string" } }, { "name": "active_on", "in": "query", "required": false, "description": "Only events whose period contains this ISO date", "schema": { "description": "Only events whose period contains this ISO date", "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } }, { "name": "near", "in": "query", "required": false, "description": "lat,lng — switches to distance-ordered near search (no cursor)", "schema": { "description": "lat,lng — switches to distance-ordered near search (no cursor)", "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?,-?\\d+(?:\\.\\d+)?$" } }, { "name": "radius", "in": "query", "required": false, "description": "Search radius in meters (near only, default 3000)", "schema": { "description": "Search radius in meters (near only, default 3000)", "type": "integer", "minimum": 1, "maximum": 50000 } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (default 20, max 100)", "schema": { "description": "Page size (default 20, max 100)", "type": "integer", "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from next_cursor", "schema": { "description": "Opaque cursor from next_cursor", "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "subjects": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "name_en": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "category": { "type": "string", "description": "'facility' | 'event' | 'service' (open vocabulary)" }, "kind": { "type": "string" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 3166-1 alpha-2; null for global services" }, "lat": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "lng": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Regional code (JP: JIS X 0402 municipality code)" }, "starts_on": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ends_on": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" } }, "required": [ "slug", "name", "name_en", "category", "kind", "country", "lat", "lng", "region", "starts_on", "ends_on", "url", "status" ], "additionalProperties": false, "description": "A recipient of appreciation." } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Opaque keyset cursor; null on the last page. Absent semantics for near queries." } }, "required": [ "subjects", "next_cursor" ], "additionalProperties": false }, { "type": "object", "properties": { "subjects": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "name_en": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "category": { "type": "string", "description": "'facility' | 'event' | 'service' (open vocabulary)" }, "kind": { "type": "string" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 3166-1 alpha-2; null for global services" }, "lat": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "lng": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Regional code (JP: JIS X 0402 municipality code)" }, "starts_on": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ends_on": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" }, "distance_m": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Distance from the query point in meters." } }, "required": [ "slug", "name", "name_en", "category", "kind", "country", "lat", "lng", "region", "starts_on", "ends_on", "url", "status", "distance_m" ], "additionalProperties": false } } }, "required": [ "subjects" ], "additionalProperties": false } ] } } } }, "400": { "description": "Invalid query or cursor", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/subjects/{slug}": { "get": { "operationId": "getSubject", "summary": "Get one subject", "description": "Subject master data by slug. Slugs may contain '/' for external namespaces (e.g. github/owner/repo).", "x-mcp-tool-name": "negirau_get_subject", "x-agent-description": "Fetch one Negirau subject by its slug.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Subject slug", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "name_en": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "category": { "type": "string", "description": "'facility' | 'event' | 'service' (open vocabulary)" }, "kind": { "type": "string" }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 3166-1 alpha-2; null for global services" }, "lat": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "lng": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Regional code (JP: JIS X 0402 municipality code)" }, "starts_on": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ends_on": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status": { "type": "string" } }, "required": [ "slug", "name", "name_en", "category", "kind", "country", "lat", "lng", "region", "starts_on", "ends_on", "url", "status" ], "additionalProperties": false, "description": "A recipient of appreciation." } } } }, "404": { "description": "Unknown subject", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/subjects/{slug}/reactions": { "get": { "operationId": "getSubjectReactions", "summary": "Weekly reaction summary (bucketized)", "description": "Reaction counts for one ISO week, as buckets only — exact numbers are never published (anti-ranking discipline).", "x-mcp-tool-name": "negirau_get_reactions", "x-agent-description": "How much appreciation a subject received in a week, as coarse buckets like '100+'.", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Subject slug", "schema": { "type": "string" } }, { "name": "period", "in": "query", "required": false, "description": "ISO week (default: current week)", "schema": { "description": "ISO week (default: current week)", "type": "string", "pattern": "^(?\\d{4})-W(?\\d{2})$" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "slug": { "type": "string" }, "period": { "type": "string", "description": "ISO week id, e.g. 2026-W33" }, "window": { "type": "object", "properties": { "start": { "type": "string" }, "end": { "type": "string" } }, "required": [ "start", "end" ], "additionalProperties": false }, "total": { "type": "string", "enum": [ "0", "1-9", "10-99", "100+" ], "description": "Bucketized count; exact numbers are never published." }, "by_type": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string", "enum": [ "0", "1-9", "10-99", "100+" ], "description": "Bucketized count; exact numbers are never published." } } }, "required": [ "slug", "period", "window", "total", "by_type" ], "additionalProperties": false } } } }, "400": { "description": "Invalid query or cursor", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } }, "404": { "description": "Unknown subject", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } } } } }, "/activity": { "get": { "operationId": "getActivity", "summary": "Map activity grid", "description": "Which geohash cells received reactions this week, and how recently. Freshness only — no quantities (the lights map contract).", "x-mcp-tool-name": "negirau_get_activity", "x-agent-description": "Weekly appreciation activity per map grid cell inside a bounding box.", "parameters": [ { "name": "bbox", "in": "query", "required": true, "description": "minLng,minLat,maxLng,maxLat", "schema": { "type": "string", "pattern": "^-?\\d+(?:\\.\\d+)?(?:,-?\\d+(?:\\.\\d+)?){3}$", "description": "minLng,minLat,maxLng,maxLat" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "period": { "type": "string", "description": "ISO week id of the aggregation window" }, "cells": { "type": "array", "items": { "type": "object", "properties": { "geohash": { "type": "string", "description": "Precision-5 geohash cell" }, "last_day": { "type": "string", "description": "Most recent ISO day with activity in the window" } }, "required": [ "geohash", "last_day" ], "additionalProperties": false } } }, "required": [ "period", "cells" ], "additionalProperties": false } } } }, "400": { "description": "Invalid query or cursor", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } } } } } } } }