# kotobase

> Knowledge Graph BaaS for engineers and enterprises on kotoba (a Datomic-over-IPFS knowledge graph). Build tenant graphs with Datomic/Datalog, SPARQL/Cypher-style query, KG ingest, MCP tools, and durable content-addressed graph hosting over IPFS.

kotobase.net is the edge API. It exposes tenant-scoped knowledge graph BaaS plus standard IPFS pinning. 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.kotobase.net/ipfs/<cid>.

## Interfaces

- Datomic Client API (canonical): POST https://datomic.kotobase.net/api/{q,qseq,transact,pull,datoms,db,tx-range,with}. EDN or Transit-JSON; Bearer JWT or CACAO. `https://kotobase.net/api/*` is the same-handler compatibility alias. This is Client API shape compatibility, not proprietary Datomic wire compatibility.
- 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; legacy datomic.*; graph.sparql/graph.query (SPARQL/Cypher), kg.query, kg.ingest/kg.ingest_batch. New Datomic clients use the Client API origin above.
- MCP (AI agents): POST https://kotobase.net/mcp (streamable-HTTP JSON-RPC) — tools generated from the same lexicons. `kotobase mcp` emits the client config.

## Plans

Three plans, separated by who carries operational responsibility:

- P2P (free, self-serve): the operator carries NO responsibility. No availability commitment, no service credits, no support obligation. 512 MiB / 50 pins on the shared endpoint; unmetered on your own peer.
- Secure Managed (self-serve subscription): Gftd Japan K.K. operates the service and is accountable for it. 99.9% monthly availability SLA with service credits, one-business-day incident acknowledgement, 500 GiB / 10,000 pins included.
- Enterprise (contract, hello@gftd.co.jp): proposed dedicated infrastructure, residency, customer-held key custody, read audit, 99.999% SLA, and 24x7 support are gated on a signed contract and deployment qualification. The DPA template requires counsel approval and no approved BAA is offered today. SOC 2 Type II / ISO 27001 / ISMAP are in preparation — no report or certificate has been issued. The shared production endpoint does not carry Enterprise commitments.

Legacy tier strings still resolve: free -> p2p; starter/standard/pro -> secure-managed; regulated -> enterprise. See https://github.com/gftdcojp/net-kotobase/blob/main/docs/PLANS.md

## Docs

- [Full docs](https://kotobase.net/llms-full.txt): complete API + usage reference in one plain-text file.
- [Kotobase for Obsidian](https://kotobase.net/obsidian): keep Markdown as the source of truth, query relationships across notes, sync without silent overwrites, and give AI bounded context instead of a whole vault.
- [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.
- Tenant graph BaaS includes kg.ingest / kg.ingest_batch and the tenant-capability Datom write plane where enabled; operator-only paths remain gated.
- Roadmap: sk_live_* API keys (today auth is gftd-AUTHN JWT or CACAO); PinStatus delegates (swarm multiaddrs).

## Paid API (x402 / USDC)

Per-request content reads are payable in USDC on Base L2 via the x402 protocol
(HTTP 402 Payment Required) — agent-native, no account or subscription needed:

- Storage read: `GET /x402/ipfs/{cid}` — $0.001 USDC per content-addressed read.
- Knowledge-graph query: `POST /x402/xrpc/{method}` — $0.002 USDC per query.
  Read methods only (datomic.q, graph.sparql, graph.query, datomic.datoms,
  datomic.pull, …); the query body carries an explicit graph CID, no account.
  Example: `POST /x402/xrpc/graph.sparql` with
  `{"graph":"bafy…","sparql":"SELECT (COUNT(?e) AS ?c) WHERE { ?e <:a> ?v }"}`.
- Discover: https://kotobase.net/.well-known/x402
- Facilitator + full catalog across services: https://x402.nexus/catalog