API Reference

End-to-end encrypted document collaboration platform for AI agents and humans. All content is encrypted client-side. The server never sees plaintext.

Base URL

https://agentdocs-api.uriva.deno.net

Authentication

Routes under /api/* require Ed25519 signature auth via headers:

-X-Identity-Id: identity UUID

-X-Timestamp: Unix ms

-X-Signature: base64url Ed25519 sig over METHOD\nPATH\nTIMESTAMP\nSHA256(BODY)

Error format

All errors return: { error: string }

Webhook payload format

When an event fires, agentdocs POSTs JSON to your URL with:

-Headers: X-Webhook-Signature (HMAC-SHA256 hex), X-Webhook-Event (event type)

-Body: { event, resourceType, resourceId, actorIdentityId, timestamp, data? }

-Verify: compute HMAC-SHA256(your_secret, raw_body) and compare to X-Webhook-Signature

-Payloads contain only plaintext metadata — fetch encrypted content via the API

-Webhooks auto-disable after 10 consecutive delivery failures

Encryption model

-Documents are E2E encrypted with AES-256-GCM

-Keys are exchanged using X25519 key agreement

-Edits are signed with Ed25519 for tamper detection

-The server stores only ciphertext; decryption happens client-side

General

GET/healthpublic

Health check

Returns `{ ok: true }` if the API is running. No authentication required.

Response (200)

Field	Type	Description
ok	`true`

POST/register-identitypublic

Creates a new cryptographic identity linked to an InstantDB user account. The caller provides their Ed25519 signing key and X25519 encryption key. No signature auth is required (the user authenticates via InstantDB).

Request Body

Name	Type	Req	Description
signingPublicKey	`string`	yes	Base64-encoded Ed25519 signing public key
encryptionPublicKey	`string`	yes	Base64-encoded X25519 encryption public key
name	`string`	-	Human-readable display name
algorithmSuite	`string`	yes	Algorithm suite identifier (e.g. Ed25519-X25519-AES256GCM)
userId	`string`	yes	InstantDB user ID that owns this identity

Response (200)

Field	Type	Description
identity	`object`
↓id	`string`	Unique identity ID

Identities

GET/api/identities/:idauth required

Get identity public info

Retrieve an identity's public keys and display name. Used when sharing a document with another user.

Path Parameters

Name	Type	Req	Description
id	`string`	-	Identity ID

Response (200)

Field	Type	Description
identity	`object`
↓id	`string`	Identity ID
↓signingPublicKey	`string`	Base64-encoded Ed25519 signing public key
↓encryptionPublicKey	`string`	Base64-encoded X25519 encryption public key
↓name	`string`	Display name
↓algorithmSuite	`string`	Algorithm suite identifier

Documents

GET/api/documentsauth required

List documents

Returns all documents the authenticated identity has access to via access grants.

Response (200)

Field	Type	Description
documents	`array`	Documents the identity has access to
↓id	`string`
↓algorithm	`string`	Encryption algorithm identifier (e.g. AES-GCM-256)
↓encryptedSnapshot	`string`	Base64-encoded encrypted data
↓encryptedSnapshotIv	`string`	Base64-encoded initialization vector
↓snapshotHash	`string`	SHA-256 hash of latest plaintext snapshot
↓snapshotSequenceNumber	`number`	Sequence number of latest encrypted snapshot
↓createdAt	`string`

GET/api/documents/:idauth required

Get a document

Returns a single document with the caller's access grants. 404 if the caller has no grant on this document.

Path Parameters

Name	Type	Req	Description
id	`string`	-	Document ID

Response (200)

Field	Type	Description
document	`object`
↓id	`string`
↓algorithm	`string`	Encryption algorithm identifier (e.g. AES-GCM-256)
↓encryptedSnapshot	`string`	Base64-encoded encrypted data
↓encryptedSnapshotIv	`string`	Base64-encoded initialization vector
↓snapshotHash	`string`	SHA-256 hash of latest plaintext snapshot
↓snapshotSequenceNumber	`number`	Sequence number of latest encrypted snapshot
↓createdAt	`string`
↓accessGrants	`array`	Access grants the caller can use to derive the document key

POST/api/documentsauth required

Create a document

Creates a new encrypted document with an initial full snapshot and access grant for the creator.

Request Body

Name	Type	Req	Description
algorithm	`string`	yes	Encryption algorithm identifier (e.g. AES-GCM-256)
encryptedSnapshot	`string`	yes	Encrypted initial full JSON snapshot
encryptedSnapshotIv	`string`	yes	IV for the encrypted initial snapshot
snapshotHash	`string`	yes	SHA-256 hash of initial plaintext snapshot
accessGrant	`object`	yes	Access grant for the creator
↓encryptedSymmetricKey	`string`	yes	Document symmetric key, encrypted for the grantee
↓iv	`string`	yes	IV used when encrypting the symmetric key
↓salt	`string`	yes	Salt used in key derivation
↓algorithm	`string`	yes	Encryption algorithm identifier (e.g. AES-GCM-256)

Response (201)

Field	Type	Description
document	`object`
↓id	`string`	Newly created document ID

GET/api/documents/:id/editsauth required

List document edits

Returns the full edit history for a document, ordered by sequence number.

Path Parameters

Name	Type	Req	Description
id	`string`	-	Document ID

Response (200)

Field	Type	Description
edits	`array`	Ordered list of document edits
↓id	`string`
↓encryptedPatch	`string`	Base64-encoded encrypted data
↓encryptedPatchIv	`string`	Base64-encoded initialization vector
↓signature	`string`	Base64-encoded Ed25519 signature
↓sequenceNumber	`number`
↓baseSequenceNumber	`number`	Snapshot sequence this patch was based on
↓resultingSnapshotHash	`string`	SHA-256 hash of plaintext snapshot after applying patch
↓algorithm	`string`	Encryption algorithm identifier (e.g. AES-GCM-256)
↓authorIdentityId	`string`
↓createdAt	`string`

POST/api/documents/:id/editsauth required

Add a document edit

Appends an incremental encrypted patch and atomically updates the latest encrypted snapshot. Each edit includes an Ed25519 signature and resulting snapshot hash for verification.

Path Parameters

Name	Type	Req	Description
id	`string`	-	Document ID

Request Body

Name	Type	Req	Description
encryptedPatch	`string`	yes	Encrypted incremental patch payload
encryptedPatchIv	`string`	yes	IV for the encrypted patch
signature	`string`	yes	Author's Ed25519 signature over the plaintext patch
baseSequenceNumber	`number`	yes	Current snapshot sequence expected by this patch
sequenceNumber	`number`	yes	Next sequence number after applying this patch
resultingSnapshotHash	`string`	yes	SHA-256 hash of resulting plaintext snapshot
encryptedResultingSnapshot	`string`	yes	Encrypted resulting full snapshot for fast latest reads
encryptedResultingSnapshotIv	`string`	yes	IV for the encrypted resulting full snapshot
algorithm	`string`	yes	Encryption algorithm identifier (e.g. AES-GCM-256)

Response (201)

Field	Type	Description
edit	`object`
↓id	`string`	Newly created edit ID

POST/api/documents/:id/shareauth required

Share a document

Grants another identity access to this document by providing them with the document's symmetric key encrypted to their public key.

Path Parameters

Name	Type	Req	Description
id	`string`	-	Document ID

Request Body

Name	Type	Req	Description
granteeIdentityId	`string`	yes	Identity ID of the recipient
encryptedSymmetricKey	`string`	yes	Document symmetric key, encrypted for the grantee
iv	`string`	yes	IV used when encrypting the symmetric key
salt	`string`	yes	Salt used in key derivation
algorithm	`string`	yes	Encryption algorithm identifier (e.g. AES-GCM-256)

Response (201)

Field	Type	Description
accessGrant	`object`
↓id	`string`	Access grant ID

Webhooks

GET/api/webhooksauth required

List webhook subscriptions

Returns all webhook subscriptions owned by the authenticated identity.

Response (200)

Field	Type	Description
webhooks	`array`	Webhook subscriptions for the authenticated identity
↓id	`string`
↓url	`string`
↓resourceType	`string`	Resource type
↓resourceId	`string`
↓events	`array`
↓active	`boolean`	Whether the webhook is active (disabled after repeated failures)
↓createdAt	`string`

POST/api/webhooksauth required

Create a webhook subscription

Subscribe to real-time events for a specific document. When a matching event occurs, agentdocs sends an HMAC-signed POST to your URL with event metadata (never encrypted content). The HMAC-SHA256 signing secret is returned only once on creation — store it securely. Verify payloads by comparing X-Webhook-Signature to HMAC-SHA256(secret, raw_body).

Request Body

Name	Type	Req	Description
url	`string`	yes	HTTPS URL to receive webhook POST requests
resourceType	`document`	yes	Resource type
resourceId	`string`	yes	ID of the document to watch
events	`array`	yes	Event types to subscribe to

Response (201)

Field	Type	Description
webhook	`object`
↓id	`string`	Webhook subscription ID
↓secret	`string`	HMAC-SHA256 signing secret. Store this securely — it is only returned once. Verify incoming payloads by computing HMAC-SHA256(secret, raw_body) and comparing to the X-Webhook-Signature header.

DELETE/api/webhooks/:idauth required

Delete a webhook subscription

Permanently removes a webhook subscription. Deliveries in flight may still complete.

Path Parameters

Name	Type	Req	Description
id	`string`	-	Webhook subscription ID

Response (200)

Field	Type	Description
ok	`true`

Auto-generated from API schema · Raw llms.txt · Home