Ontology Sharing

The Ontology Sharing API lets an ontology owner grant another user viewer or editor access to an ontology, and lets the recipient accept, leave, and reconcile shares from their inbox. Sharing issues a scoped token to the recipient under the hood; the raw token is never returned to the sharer — it is delivered to the recipient and claimed on accept. All paths are relative to the base URL and require authentication. All responses use the standard envelope.

Endpoints split into sharer-side (you own the ontology and grant access) and recipient-side (an ontology has been shared with you). Recipient-side endpoints additionally rely on your Supabase session, sent via the X-Supabase-Token header, so row-level security scopes the results to you.

Sharer-side

Grant another user access to one of your ontologies. Identify the recipient by sub, by email, or by username together with organization.

POST /ontologies/share

Parameter	In	Required	Default	Description
`project_id`	body	yes	—	ID of the ontology to share.
`recipient`	body	yes	—	Recipient object: `{ "sub": "..." }`, `{ "email": "..." }`, or `{ "username": "...", "organization": "..." }`.
`share_role`	body	yes	—	`"viewer"` or `"editor"`.
`expires_in_minutes`	body	no	`null`	Lifetime of the share; omit or `null` for no expiration.

curl -X POST "$BASE_URL/ontologies/share" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "'$PROJECT_ID'",
    "recipient": { "email": "alice@example.com" },
    "share_role": "viewer"
  }'

{
  "status": "success",
  "message": "Ontology shared successfully.",
  "data": {
    "share_id": "shr_a1b2...",
    "project_id": "proj_123",
    "share_role": "viewer",
    "status": "pending"
  }
}

List shares (outbox)

Return every share you have created, most recent first. Optionally filter to a single ontology.

GET /ontologies/share/list

Parameter	In	Required	Default	Description
`project_id`	query	no	—	Filter the outbox to a single ontology.

curl "$BASE_URL/ontologies/share/list" \
  -H "Authorization: Bearer $TOKEN"

data is an array of share objects (share_id, project_id, share_role, status, recipient identity, and timestamps). Change a share between viewer and editor in place — the recipient is not forced to re-accept. Updating to the role it already has is a no-op that returns data.changed = false.

POST /ontologies/share/update-role

Parameter	In	Required	Default	Description
`share_id`	body	yes	—	The share to update.
`share_role`	body	yes	—	New role: `"viewer"` or `"editor"`.

curl -X POST "$BASE_URL/ontologies/share/update-role" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "share_id": "shr_a1b2...", "share_role": "editor" }'

{
  "status": "success",
  "message": "Share role updated successfully.",
  "data": { "share_id": "shr_a1b2...", "share_role": "editor", "changed": true }
}

Revoke access you previously granted. Pass either a share_id, or a project_id together with a recipient_sub. Revoking is idempotent.

POST /ontologies/share/revoke

Parameter	In	Required	Default	Description
`share_id`	body	conditional	—	The share to revoke.
`project_id`	body	conditional	—	Ontology ID — use with `recipient_sub` instead of `share_id`.
`recipient_sub`	body	conditional	—	Recipient’s auth ID — use with `project_id`.

curl -X POST "$BASE_URL/ontologies/share/revoke" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "share_id": "shr_a1b2..." }'

{
  "status": "success",
  "message": "Share revoked successfully.",
  "data": { "share_id": "shr_a1b2...", "status": "revoked" }
}

Recipient-side

List inbox

Return every share currently visible to you as a recipient — pending invitations and already-accepted shares. Each entry is annotated with has_local_token so you can tell “accepted on this workspace” from “accepted elsewhere”.

GET /ontologies/share/inbox

This endpoint takes no parameters.

curl "$BASE_URL/ontologies/share/inbox" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Supabase-Token: $SUPABASE_TOKEN"

data is an array of inbox entries (share_id, project_id, share_role, status, has_local_token, sharer identity, and timestamps). Claim a pending share. The scoped token is vaulted into your workspace so you can open the shared ontology. Idempotent for shares already accepted on this workspace.

POST /ontologies/share/accept

Parameter	In	Required	Default	Description
`share_id`	body	yes	—	The share to accept.

curl -X POST "$BASE_URL/ontologies/share/accept" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Supabase-Token: $SUPABASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "share_id": "shr_a1b2..." }'

{
  "status": "success",
  "message": "Share accepted successfully.",
  "data": { "share_id": "shr_a1b2...", "status": "accepted" }
}

Detach yourself from a share you previously accepted (or a pending one). This removes the local token and marks the share left. Idempotent.

POST /ontologies/share/leave

Parameter	In	Required	Default	Description
`share_id`	body	yes	—	The share to leave.

curl -X POST "$BASE_URL/ontologies/share/leave" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Supabase-Token: $SUPABASE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "share_id": "shr_a1b2..." }'

{
  "status": "success",
  "message": "Share left successfully.",
  "data": { "share_id": "shr_a1b2...", "status": "left" }
}

Sync inbox

Reconcile your locally-vaulted shares against the source of truth. Local entries whose share is no longer accepted (revoked, superseded, left, or missing) are pruned. Use this as a safety net to catch up after a missed real-time update.

POST /ontologies/share/sync

This endpoint takes no parameters.

curl -X POST "$BASE_URL/ontologies/share/sync" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Supabase-Token: $SUPABASE_TOKEN"

{
  "status": "success",
  "message": "Inbox synced successfully.",
  "data": { "pruned": 1, "active": 3 }
}

Introduction

Get Started

Platform

Integrations

Examples

Vadalog Reference

Resources

Sharer-side

List shares (outbox)

Recipient-side

List inbox

Sync inbox

​Sharer-side

​Share an ontology

​List shares (outbox)

​Update a share’s role

​Revoke a share

​Recipient-side

​List inbox

​Accept a share

​Leave a share

​Sync inbox

Sharer-side

Share an ontology

List shares (outbox)

Update a share’s role

Revoke a share

Recipient-side

List inbox

Accept a share

Leave a share

Sync inbox