Home / API

The HTTP API

Everything sgit does, it does over this API. The CLI is a client; so is the browser bridge; so is anything you write. This section is the protocol surface — endpoints, headers, gates, limits and the error codes you will actually hit.

Where this came from, and how far to trust it. This section is built from a code-verified audit supplied by the SG/API team, read out of the route tables and constants at v0.33.54 rather than recalled. It is their verification, not ours: this site has not independently exercised every endpoint. Where their audit and the shipped client disagreed we checked and said so; where something is registered but unconfirmed it is labelled PROPOSED and you should not build on it yet. Same rule as the rest of this site — if it is not verified, it says so.

Base URL

https://send.sgraph.ai for the hosted service, or your own host if you run it yourself. All request and response bodies are JSON unless stated otherwise.

The one idea worth reading first

The server is a capability-checked ciphertext store, and every access-control decision it makes is a hash comparison. It stores SHA-256 of each capability key and checks H(presented) == stored. It never holds a raw key, and it never holds a private key at all.

That is what makes the rest of the design possible: a vault ID is an address rather than an account, reads are public by default because the bytes are useless without a key, and a stranger can write to your vault without ever having a credential on the platform.

The reference

Page	What is in it
Authentication	The six headers, what each gates, and the hash-comparison model
Vault objects	The pointer store — read, write, batch, destroy — plus the caching contract and storage layout
Append lanes	The six append endpoints: the vault-to-vault message transport
Errors and limits	400, 403, 413, 507 — what each actually means, and the ceilings that produce them

Four capabilities

Most of the API surface is one of four capability tiers. They are separated so that holding one tells you nothing about the others:

Capability	Presented as	Grants
`append_token`	a field in the request body	Write to one append lane. Nothing else — not even listing it
`enum_key`	`x-sgraph-vault-enum-key`	List, fetch and mark-processed on append lanes
`write_key`	`x-sgraph-vault-write-key`	Write and delete objects; configure and purge lanes
private key	never presented	Decryption, client-side only

The fourth row is the point of the design rather than a footnote: the server cannot decrypt anything it stores, so the strongest capability in the system is the one it never sees.

Where to start

Sending an encrypted message between two vaults → Vault messaging, which composes append lanes with PKI.
Reading or writing files → Vault objects.
Building a vault app in the browser → the SG bridge wraps this API so you never write HTTP.
Using the CLI instead → Quickstart.

Open questions we will not guess at

Three items came through the audit unresolved. They are listed rather than documented, because a confident page about an endpoint that does not exist is worse than no page:

Item	Status
`GET /api/vault/zip/{vault_id}`	UNRESOLVED — registered in the route table, marked PROPOSED in the team’s reality document. Not documented either way until that is reconciled
`/join/*`	UNRESOLVED — the reality document lists three live endpoints, but the routes are not registered in the deployed app. Not documented
Client-side lane addressing	PROPOSED — `append_token = H(public key)` is the intended model; no shipped command emits it. See the addressing note for what to do meanwhile