EVC Team Relay

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

Environment variables

Quick start

# 1. Authenticate — get a JWT token (stored in env var, not visible in ps)
export RELAY_TOKEN=$(scripts/auth.sh)

# 2. List shares to find available documents
scripts/list-shares.sh

# 3. Read a file from a folder share BY PATH (most common)
scripts/read-file.sh \x3Cfolder_share_id> "Marketing/plan.md"

# 4. Create or update a file in a folder share
scripts/upsert-file.sh \x3Cfolder_share_id> "note.md" "# Content"

# 5. List all files in a folder share
scripts/list-files.sh \x3Cfolder_share_id>

# 6. Delete a file from a folder share
scripts/delete-file.sh \x3Cfolder_share_id> "old-note.md"

# 7. Read a doc share (single document, share_id = doc_id)
scripts/read.sh \x3Cshare_id>

# 8. Write to a doc share
scripts/write.sh \x3Cshare_id> \x3Cshare_id> "# Updated content"

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

Two kinds of shares

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

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:

curl -s -X POST "$RELAY_CP_URL/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email": "'$RELAY_EMAIL'", "password": "'$RELAY_PASSWORD'"}' \
  | jq -r '.access_token'

Response:

{
  "access_token": "eyJ...",
  "refresh_token": "...",
  "token_type": "bearer",
  "expires_in": 3600
}

Use the access_token as Authorization: Bearer \x3Ctoken> header on all subsequent requests.

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

curl -s -X POST "$RELAY_CP_URL/v1/auth/refresh" \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "'$REFRESH_TOKEN'"}'

Listing shares

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

curl -s "$RELAY_CP_URL/v1/shares" \
  -H "Authorization: Bearer $TOKEN" | jq

Response (array):

[
  {
    "id": "a1b2c3d4-...",
    "kind": "doc",
    "path": "Projects/meeting-notes.md",
    "visibility": "private",
    "is_owner": true,
    "user_role": null,
    "web_published": false
  },
  {
    "id": "e5f6g7h8-...",
    "kind": "folder",
    "path": "Projects/",
    "visibility": "private",
    "is_owner": false,
    "user_role": "editor"
  }
]

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

scripts/list-files.sh \x3Cshare_id>

Response:

{
  "doc_id": "e5f6g7h8-...",
  "files": {
    "meeting-notes.md": {"doc_id": "abc123-...", "type": "markdown"},
    "project-plan.md": {"doc_id": "def456-...", "type": "markdown"}
  }
}

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)

scripts/read-file.sh \x3Cfolder_share_id> "Marketing/plan.md"

This resolves the path to a doc_id internally and returns:

{
  "doc_id": "abc123-...",
  "content": "# Marketing Plan\
\
Content here...",
  "format": "text",
  "path": "Marketing/plan.md"
}

By doc_id (low-level)

scripts/read.sh \x3Cshare_id> [doc_id] [key]

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

Writing files

Folder shares — use upsert-file.sh

# Create or update — auto-detects which operation is needed
scripts/upsert-file.sh \x3Cfolder_share_id> "note.md" "# Updated content"

# Pipe content from stdin
echo "# Content" | scripts/upsert-file.sh \x3Cfolder_share_id> "note.md" -

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

Doc shares — use write.sh

scripts/write.sh \x3Cshare_id> \x3Cshare_id> "# Updated Notes"

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

Common workflows

Read a specific note by path (most common)

# If you know the folder share_id:
scripts/read-file.sh \x3Cfolder_share_id> "Marketing/docs/plan.md"

# If you need to find the share first:
scripts/list-shares.sh  # find the folder share
scripts/read-file.sh \x3Cshare_id> "path/to/file.md"

Create or update a file

# Always works, whether the file exists or not
scripts/upsert-file.sh \x3Cfolder_share_id> "note.md" "# Content"

Delete a file

scripts/delete-file.sh \x3Cfolder_share_id> "old-note.md"

Error codes

Terminology

References

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