EVC Team Relay

REST API skill for reading and writing collaborative Obsidian vault documents via EVC Team Relay.

Environment variables

Variable	Required	Description
INLINECODE0	yes	Control plane URL, e.g. INLINECODE1
INLINECODE2

yes | User email for authentication | | RELAY_PASSWORD | yes | User password | | RELAY_TOKEN | no | JWT token (set via export RELAY_TOKEN=$(scripts/auth.sh)) |

Quick start

CODEBLOCK0

All scripts accept the token via RELAY_TOKEN env var (preferred) or as the first CLI argument (backward-compatible).

Two kinds of shares

	Doc share	Folder share
Contains	Single document	Multiple files
docid

Same as shareid | Each file has its own doc_id (in folder metadata) | | Read | read.sh <share_id> | read-file.sh <share_id> "path/to/file.md" | | Write | write.sh <share_id> <share_id> <content> | upsert-file.sh <share_id> "path" <content> | | Delete | N/A | delete-file.sh <share_id> "path" |

Most shares are folder shares. Use read-file.sh and upsert-file.sh — they handle path resolution automatically.

Warning: write.sh does NOT work for folder shares — it writes content but does not register the file in folder metadata, so Obsidian will never see it. The script detects folder shares and refuses with an error.

Scripts reference

Script	Purpose	Args
INLINECODE15	Get JWT token	—
INLINECODE16

List all shares | [kind] [owned_only] | | list-files.sh | List files in folder share | <share_id> | | read-file.sh | Read file by path (folder share) | <share_id> <file_path> | | read.sh | Read by doc_id (low-level) | <share_id> [doc_id] | | upsert-file.sh | Create/update file (folder share) | <share_id> <file_path> <content> | | write.sh | Write by doc_id (doc shares only) | <share_id> <doc_id> <content> | | delete-file.sh | Delete file from folder share | <share_id> <file_path> | | create-file.sh | Create new file (low-level) | <share_id> <file_path> <content> |

Bold = recommended for most use cases. All scripts use RELAY_TOKEN env var (or accept token as first arg).

Authentication

All API calls require a Bearer JWT token. Get one via login:

CODEBLOCK1

Response:
CODEBLOCK2

Use the access_token as Authorization: Bearer <token> header on all subsequent requests.

When the token expires (1 hour), refresh it:
CODEBLOCK3

Listing shares

Shares are the access units — each share maps to a document or folder in the Obsidian vault.

CODEBLOCK4

Response (array):
CODEBLOCK5

Key fields:

• - id — share UUID, used as share_id in all operations
• kind — doc (single file) or folder (directory)
• path — Obsidian vault-relative path
• user_role — viewer (read-only), editor (read-write), or null (owner)

Filter options: ?kind=doc, ?owned_only=true, ?member_only=true, ?skip=0&limit=50.

Listing files in a folder share

CODEBLOCK6

Response:
CODEBLOCK7

Each key is the file's path within the folder. The doc_id field is the document identifier used for content operations. The share_id for content requests is always the folder share's ID.

Note: The API response uses id as the field name. This is the same as doc_id — use it wherever doc_id is needed.

Reading files

By path (recommended for folder shares)

CODEBLOCK8

This resolves the path to a doc_id internally and returns:
CODEBLOCK9

By doc_id (low-level)

CODEBLOCK10

For doc shares, omit docid (defaults to shareid). For folder shares, pass the file's doc_id from list-files.sh.

Writing files

Folder shares — use upsert-file.sh

CODEBLOCK11

Response includes an operation field: "created" or "updated".

Doc shares — use write.sh

CODEBLOCK12

write.sh refuses folder shares — if you accidentally pass a folder shareid as docid, it detects this and exits with an error directing you to upsert-file.sh.

Common workflows

Read a specific note by path (most common)

CODEBLOCK13

Create or update a file

CODEBLOCK14

Delete a file

CODEBLOCK15

Error codes

Status	Meaning
400	Invalid share_id format
401

Missing or expired token — re-authenticate | | 403 | Insufficient permissions (viewer trying to write, or non-member) | | 404 | Share or file not found (check path spelling, use list-files.sh to verify) | | 422 | Missing required field (share_id, content) | | 502 | Relay server unavailable — retry later |

Terminology

Term	Meaning
INLINECODE58	UUID of a share (doc or folder). Used for ACL checks in all requests.
INLINECODE59

UUID of an individual document. For doc shares, equals shareid. For folder shares, each file has its own docid. | | id | Same as doc_id — the API response field name. Use interchangeably. | | file_path | Relative path within a folder share (e.g. "Marketing/plan.md"). |

References

• - references/api.md — full API reference with all endpoints