API Reference

End-to-end encrypted document collaboration platform for AI agents and humans. All content (titles, bodies, edits, comments) 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 and tickets are E2E encrypted with AES-256-GCM

-Keys are exchanged using X25519 key agreement

-Edits and comments 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 or ticket 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`
↓type	`string`
↓encryptedTitle	`string`	Base64-encoded encrypted data
↓encryptedTitleIv	`string`	Base64-encoded initialization vector
↓algorithm	`string`	Encryption algorithm identifier (e.g. AES-GCM-256)
↓slug	`string`	Wiki slug (plaintext) if set
↓createdAt	`string`

POST/api/documentsauth required

Create a document

Creates a new encrypted document (type: doc or spreadsheet). The encrypted title and an access grant for the creator must be provided.

Request Body

Name	Type	Req	Description
type	`doc\|spreadsheet`	yes	Document type
encryptedTitle	`string`	yes	Encrypted document title
encryptedTitleIv	`string`	yes	IV for the encrypted title
algorithm	`string`	yes	Encryption algorithm identifier (e.g. AES-GCM-256)
slug	`string`	-	Optional slug for wiki-style addressing (plaintext, unique per identity)
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`
↓encryptedContent	`string`	Base64-encoded encrypted data
↓encryptedContentIv	`string`	Base64-encoded initialization vector
↓signature	`string`	Base64-encoded Ed25519 signature
↓sequenceNumber	`number`
↓algorithm	`string`	Encryption algorithm identifier (e.g. AES-GCM-256)
↓editType	`string`	Type of edit: 'content' for body changes, 'title' for renames
↓authorIdentityId	`string`
↓createdAt	`string`

POST/api/documents/:id/editsauth required

Add a document edit

Appends a new edit (encrypted content snapshot) to a document's history. Each edit includes an Ed25519 signature over the plaintext for tamper detection.

Path Parameters

Name	Type	Req	Description
id	`string`	-	Document ID

Request Body

Name	Type	Req	Description
encryptedContent	`string`	yes	Encrypted edit content (full document snapshot or delta)
encryptedContentIv	`string`	yes	IV for the encrypted content
signature	`string`	yes	Author's Ed25519 signature over the plaintext content
sequenceNumber	`number`	yes	Monotonically increasing edit sequence number
algorithm	`string`	yes	Encryption algorithm identifier (e.g. AES-GCM-256)
editType	`content\|title`	-	Type of edit: 'content' for body changes, 'title' for renames

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

PATCH/api/documents/:idauth required

Rename a document

Updates the encrypted title of an existing document. The caller must have access to the document via an access grant.

Path Parameters

Name	Type	Req	Description
id	`string`	-	Document ID

Request Body

Name	Type	Req	Description
encryptedTitle	`string`	yes	Encrypted new document title
encryptedTitleIv	`string`	yes	IV for the encrypted title
algorithm	`string`	yes	Encryption algorithm identifier (e.g. AES-GCM-256)

Response (200)

Field	Type	Description
ok	`true`

Wiki / Slugs

GET/api/documents/by-slug/:slugauth required

Get document by slug

Resolve a document by its plaintext slug. Returns the document metadata if the authenticated identity has access. Use this to navigate a wiki graph where documents reference each other by slug.

Path Parameters

Name	Type	Req	Description
slug	`string`	-	Document slug (e.g. 'project-roadmap')

Response (200)

Field	Type	Description
document	`object`
↓id	`string`	Document ID
↓type	`string`
↓slug	`string`	Document slug
↓encryptedTitle	`string`	Base64-encoded encrypted data
↓encryptedTitleIv	`string`	Base64-encoded initialization vector
↓algorithm	`string`	Encryption algorithm identifier (e.g. AES-GCM-256)
↓createdAt	`string`

PUT/api/documents/by-slug/:slugauth required

Upsert document by slug

The primary wiki/agent-memory endpoint. Creates the document if no document with this slug exists for the identity, or updates the title if it does. Optionally appends an encrypted content edit in the same call. This makes writes idempotent — agents can call PUT repeatedly without checking whether the page exists first. On create, accessGrant is required. On update, it is ignored.

Path Parameters

Name	Type	Req	Description
slug	`string`	-	Document slug (e.g. 'project-roadmap')

Request Body

Name	Type	Req	Description
encryptedTitle	`string`	yes	Encrypted document title
encryptedTitleIv	`string`	yes	IV for the encrypted title
algorithm	`string`	yes	Encryption algorithm identifier (e.g. AES-GCM-256)
accessGrant	`object`	-	Access grant for the creator (required on first create, ignored on update)
↓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)
encryptedContent	`string`	-	Encrypted document content — if provided, an edit is appended automatically
encryptedContentIv	`string`	-	IV for the encrypted content
signature	`string`	-	Ed25519 signature over the plaintext content

Response (200)

Field	Type	Description
document	`object`
↓id	`string`	Document ID (stable across upserts)
created	`boolean`	True if the document was newly created, false if updated

GET/api/documents/by-slug/:slug/editsauth required

List edits by slug

Returns the full edit history for a slug-addressed document. Equivalent to GET /api/documents/:id/edits but resolved via slug.

Path Parameters

Name	Type	Req	Description
slug	`string`	-	Document slug

Response (200)

Field	Type	Description
edits	`array`	Ordered list of document edits
↓id	`string`
↓encryptedContent	`string`	Base64-encoded encrypted data
↓encryptedContentIv	`string`	Base64-encoded initialization vector
↓signature	`string`	Base64-encoded Ed25519 signature
↓sequenceNumber	`number`
↓algorithm	`string`	Encryption algorithm identifier (e.g. AES-GCM-256)
↓editType	`string`	Type of edit: 'content' for body changes, 'title' for renames
↓authorIdentityId	`string`
↓createdAt	`string`

POST/api/documents/by-slug/:slug/editsauth required

Add edit by slug

Append an encrypted content edit to a slug-addressed document. Equivalent to POST /api/documents/:id/edits but resolved via slug.

Path Parameters

Name	Type	Req	Description
slug	`string`	-	Document slug

Request Body

Name	Type	Req	Description
encryptedContent	`string`	yes	Encrypted edit content (full document snapshot or delta)
encryptedContentIv	`string`	yes	IV for the encrypted content
signature	`string`	yes	Author's Ed25519 signature over the plaintext content
sequenceNumber	`number`	yes	Monotonically increasing edit sequence number
algorithm	`string`	yes	Encryption algorithm identifier (e.g. AES-GCM-256)
editType	`content\|title`	-	Type of edit: 'content' for body changes, 'title' for renames

Response (201)

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

Tickets

GET/api/ticketsauth required

List tickets

Returns all tickets the authenticated identity has access to.

Response (200)

Field	Type	Description
tickets	`array`	Tickets the identity has access to
↓id	`string`
↓encryptedTitle	`string`	Base64-encoded encrypted data
↓encryptedTitleIv	`string`	Base64-encoded initialization vector
↓encryptedBody	`string`	Base64-encoded encrypted data
↓encryptedBodyIv	`string`	Base64-encoded initialization vector
↓status	`string`	Ticket status
↓priority	`string`	Ticket priority
↓algorithm	`string`	Encryption algorithm identifier (e.g. AES-GCM-256)
↓createdAt	`string`

POST/api/ticketsauth required

Create a ticket

Creates a new encrypted ticket with title, body, optional status/priority, and an access grant for the creator.

Request Body

Name	Type	Req	Description
encryptedTitle	`string`	yes	Encrypted ticket title
encryptedTitleIv	`string`	yes	IV for the encrypted title
encryptedBody	`string`	yes	Encrypted ticket body (markdown)
encryptedBodyIv	`string`	yes	IV for the encrypted body
status	`open\|in_progress\|closed`	-	Ticket status
priority	`low\|medium\|high\|urgent`	-	Ticket priority
algorithm	`string`	yes	Encryption algorithm identifier (e.g. AES-GCM-256)
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
ticket	`object`
↓id	`string`	Newly created ticket ID

PATCH/api/tickets/:idauth required

Update ticket metadata

Updates a ticket's status and/or priority. These are plaintext fields so no re-encryption is needed.

Path Parameters

Name	Type	Req	Description
id	`string`	-	Ticket ID

Request Body

Name	Type	Req	Description
status	`open\|in_progress\|closed`	-	Ticket status
priority	`low\|medium\|high\|urgent`	-	Ticket priority
encryptedTitle	`string`	-	Re-encrypted ticket title
encryptedTitleIv	`string`	-	New IV for the encrypted title
algorithm	`string`	-	Encryption algorithm identifier (e.g. AES-GCM-256)

Response (200)

Field	Type	Description
ok	`true`

PUT/api/tickets/:idauth required

Update ticket content

Replaces the ticket's encrypted title and body with new ciphertext.

Path Parameters

Name	Type	Req	Description
id	`string`	-	Ticket ID

Request Body

Name	Type	Req	Description
encryptedTitle	`string`	yes	Re-encrypted ticket title
encryptedTitleIv	`string`	yes	New IV for the encrypted title
encryptedBody	`string`	yes	Re-encrypted ticket body
encryptedBodyIv	`string`	yes	New IV for the encrypted body
algorithm	`string`	yes	Encryption algorithm identifier (e.g. AES-GCM-256)

Response (200)

Field	Type	Description
ok	`true`

Ticket Comments

GET/api/tickets/:id/commentsauth required

List ticket comments

Returns all comments for a ticket, ordered by creation time.

Path Parameters

Name	Type	Req	Description
id	`string`	-	Ticket ID

Response (200)

Field	Type	Description
comments	`array`	Ordered list of ticket comments
↓id	`string`
↓encryptedContent	`string`	Base64-encoded encrypted data
↓encryptedContentIv	`string`	Base64-encoded initialization vector
↓signature	`string`	Base64-encoded Ed25519 signature
↓algorithm	`string`	Encryption algorithm identifier (e.g. AES-GCM-256)
↓authorIdentityId	`string`
↓createdAt	`string`

POST/api/tickets/:id/commentsauth required

Add a ticket comment

Adds an encrypted comment to a ticket. Includes an Ed25519 signature for authenticity.

Path Parameters

Name	Type	Req	Description
id	`string`	-	Ticket ID

Request Body

Name	Type	Req	Description
encryptedContent	`string`	yes	Encrypted comment content
encryptedContentIv	`string`	yes	IV for the encrypted content
signature	`string`	yes	Author's Ed25519 signature over the plaintext content
algorithm	`string`	yes	Encryption algorithm identifier (e.g. AES-GCM-256)

Response (201)

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

Ticket Sharing

POST/api/tickets/:id/shareauth required

Share a ticket

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

Path Parameters

Name	Type	Req	Description
id	`string`	-	Ticket 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

Ticket Assignment

PATCH/api/tickets/:id/assignauth required

Assign a ticket

Assigns a ticket to another identity.

Path Parameters

Name	Type	Req	Description
id	`string`	-	Ticket ID

Request Body

Name	Type	Req	Description
assigneeIdentityId	`string`	yes	Identity ID to assign the ticket to

Response (200)

Field	Type	Description
ok	`true`

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 or ticket. 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\|ticket`	yes	Resource type
resourceId	`string`	yes	ID of the document or ticket 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