# kotobase

> Content-addressed pin & hosting service on kotoba (a Datomic-over-IPFS knowledge graph). Pin content by CID and have it stored durably (off-site via CAR-on-B2) and served over IPFS. Usable via the standard IPFS Pinning Service API, an XRPC API, or MCP.

kotobase.net is the edge API. A "pin" is a named commit CID in kotoba's content-addressed quad store. Auth is either a gftd-AUTHN JWT (HTTP `Authorization: Bearer <JWT>`) or a self-signed CACAO (`Authorization: CACAO <base64-cbor>` + `x-kotoba-did`). Identity: did:web:kotobase.net.

## Quick start (IPFS Pinning Service API)

```
ipfs pin remote service add kotobase https://kotobase.net <JWT>
ipfs pin remote add --service=kotobase --name=<name> <cid>
ipfs pin remote ls --service=kotobase
ipfs pin remote rm --service=kotobase --cid=<cid>
```

Retrieve any pinned CID at https://ipfs.gftd.ai/ipfs/<cid>.

## Interfaces

- IPFS Pinning Service API (PSA, https://ipfs.github.io/pinning-services-api-spec/): POST/GET/DELETE https://kotobase.net/pins (+ /pins/{requestid}). Bearer JWT or CACAO auth.
- XRPC: POST https://kotobase.net/xrpc/ai.gftd.apps.kotobase.<method> — pinCreate, pinList, pinDelete, accountCreate, accountStatus, usageGet; datomic.* (Datom/Datalog read), graph.sparql/graph.query (SPARQL/Cypher), kg.query, kg.ingest/kg.ingest_batch.
- MCP (AI agents): https://mcp.gftd.ai/mcp — tools generated from the same lexicons.

## Docs

- [Full docs](https://kotobase.net/llms-full.txt): complete API + usage reference in one plain-text file.
- [Using as a pin service](https://github.com/gftdcojp/net-kotobase/blob/main/docs/USING-AS-A-PIN-SERVICE.md): auth, pin, retrieve, query, quotas, curl examples.

## Notes

- Durability: every pinned commit is archived off-site to Backblaze B2 as one CAR object (CAR-on-B2); cold reads served via ranged GET. Scales by commit count, not block count.
- Datom writes (datomic.transact) are operator-only; tenant writes are pinCreate + kg.ingest.
- Roadmap: sk_live_* API keys (today auth is gftd-AUTHN JWT or CACAO); PinStatus delegates (swarm multiaddrs).