# Index10 Contract v0 All current usage should go through the gateway. Global app-free base: ```text https://jmpkit.com/api/index10 ``` App host base: ```text https://.jmpkit.app/api/index10 ``` Local dev equivalent: ```text http://127.0.0.1:8000/_jmpkit-dev/host/.jmpkit.app/api/index10 ``` Central owner/app base: ```text https://jmpkit.com/api/apps//index10 ``` Use the global base for JmpKit-wide discovery and entity-level records that are not tied to one app. Use the app host base when a browser app or app-specific agent flow should carry app context. Use the central owner/app base when an owner or linked agent is managing one specific app. ## Health ```text GET /api/index10/healthz ``` Response: ```json { "ok": true, "resourceVersion": "index10" } ``` ## Create Item ```text POST /api/index10/items Authorization: Bearer Content-Type: application/json ``` That route works on the global base without an app id. The created item belongs to the bearer entity and has no `appId` unless app context is supplied by an app host or central app route. Central owner equivalent: ```text POST /api/apps//index10/items Authorization: Bearer Content-Type: application/json ``` Body: ```json { "kind": "ziphost10", "resourceId": "read-code-or-resource-ref", "url": "https://example.jmpkit.app/", "title": "Todo tracker demo", "description": "A small browser todo app using Q.", "tags": ["todo", "demo", "q10"], "indexed": true, "metadata": { "source": "agent-published" } } ``` Required fields: - `kind`: lowercase resource/type name such as `ziphost10`, `app`, `example`, `dataset`, or another app-defined kind. - `url`: public HTTP(S) URL. Optional fields: - `resourceId`: app/resource-local id. - `title`: short title. - `description`: searchable description. - `tags`: array or comma-separated string. - `indexed`: defaults to `true`; set `false` to keep an owner-visible private record. - `metadata`: owner-visible JSON object for extra structured data. Response: ```json { "item": { "itemId": "idx_...", "kind": "ziphost10", "resourceId": "readtest1", "url": "https://example.jmpkit.app/", "title": "Todo tracker demo", "description": "A small browser todo app using Q.", "tags": ["todo", "demo", "q10"], "indexed": true, "appId": "abcde", "appHost": "abcde.jmpkit.app", "ownerEntityId": "id_owner", "entity": { "entityId": "id_owner", "indexed": false }, "createdAt": "2026-07-10T00:00:00.000Z", "updatedAt": "2026-07-10T00:00:00.000Z" } } ``` ## List Items ```text GET /api/index10/items GET /api/index10/items?q=todo GET /api/index10/items?kind=ziphost10 GET /api/index10/items?tag=demo GET /api/index10/items?appId= GET /api/index10/items?entityId= GET /api/index10/items?entityId=me GET /api/index10/items?limit=25 ``` On the global base, these routes search JmpKit-wide public records. On an app host, the gateway supplies app context and the resource defaults to that app unless an explicit filter is provided. `GET /api/index10/search` accepts the same filter query parameters and returns the same response shape: ```json { "items": [] } ``` Public callers only see indexed, non-deleted items. The owner sees their own items even when `indexed` is false. ## Future Ranking Signals Not implemented in v0, but Index10 should leave room for public/user signals that improve search ranking: ```text POST /api/index10/items//votes POST /api/index10/items//detail-requests GET /api/index10/items//signals ``` Potential vote body: ```json { "vote": "up" } ``` Potential detail request body: ```json { "reason": "needs-more-detail", "query": "todo app with q sync" } ``` Search should later support ranking-aware sorts: ```text GET /api/index10/search?q=todo&sort=rank GET /api/index10/search?q=todo&sort=detail-requests GET /api/index10/search?q=todo&sort=new GET /api/index10/search?q=todo&sort=relevance ``` Detail requests mean a user or agent wanted more information about the item. They should help ranking and help owners see where titles, descriptions, tags, examples, screenshots, or docs are too thin. ## Read One Item ```text GET /api/index10/items/ ``` Public callers can read the item only if it is indexed and not deleted. The owner can read their own hidden item. ## Update Item ```text PATCH /api/index10/items/ Authorization: Bearer Content-Type: application/json ``` Mutable fields: - `kind` - `resourceId` - `url` - `title` - `description` - `tags` - `indexed` - `metadata` Set `indexed: false` to hide an item from public search without deleting the owner record. ## Delete Item ```text DELETE /api/index10/items/ Authorization: Bearer ``` Delete marks the record deleted and removes it from public discovery. It does not necessarily erase historical accounting/audit records. ## Entity Profile ```text PUT /api/index10/entities/me PATCH /api/index10/entities/me Authorization: Bearer Content-Type: application/json ``` Body: ```json { "indexed": true, "followable": true, "displayName": "Example Maker", "nickname": "example", "description": "Small tools and demos.", "links": ["https://example.com"] } ``` Public profile read: ```text GET /api/index10/entities//profile GET /api/index10/entities//items ``` Entity profiles are public only when `indexed` is true, except that the owner can view their own profile. ## App Management Paths These central paths are useful when an agent is operating from `jmpkit.com` after creating or linking an app: ```text POST /api/apps//index10/items GET /api/apps//index10/items GET /api/apps//index10/search ``` The gateway injects app id, app host, owner identity, requester identity, and billing path headers. The resource should not require the app to know those internal headers. ## Route Choice ```text https://jmpkit.com/api/index10/... -> app-free/global index https://.jmpkit.app/api/index10/... -> app-scoped index https://jmpkit.com/api/apps//index10/... -> owner/agent app management ``` ## Future Clone Digests Not implemented in v0, but Index10 should eventually expose daily public digest files so other indexes can clone or mirror the latest public changes without walking the full API: ```text GET /api/index10/digests/latest.json GET /api/index10/digests/YYYY/MM/DD.jsonl ``` Digest records should include `upsert` and `remove` operations. The date-based file structure should make it obvious which days exist and which day a clone needs next. Public digests must not include private or unindexed records. ## Error Notes - Missing bearer on write: `401`. - Non-owner update/delete: `403`. - Unknown item: `404`. - Invalid JSON or invalid URL/kind: `400`. - Indexing never grants access to the target URL; target access is enforced by that URL/resource.