REST API
Every capability of Source is one operation — defined once, exposed identically as an MCP tool and a REST call. The reference below is generated from that registry, so it is always the live surface.
Conventions#
Authentication. Send an API key as a Bearer token on every request:
curl -X POST https://usesource.dev/api/v1/ops/write_file \
-H "Authorization: Bearer src_live_..." \
-H "Content-Type: application/json" \
-d '{"libraryId": "LIB_ID", "path": "/decisions/firestore.md", "content": "# Why Firestore\n..."}'
Calling operations. POST https://usesource.dev/api/v1/ops/{name} with a JSON body matching the operation's parameters. GET https://usesource.dev/api/v1/ops lists every operation with its JSON Schema; GET https://usesource.dev/api/v1/me returns the authenticated principal.
Envelope. Success is {"ok": true, "result": ...}. Every failure is {"error": {"code": ..., ...}} with a matching HTTP status:
| Status | Code | Meaning |
|---|---|---|
| 400 | invalid_input |
The body failed schema validation; issues lists why. |
| 400 | invalid_pattern |
A regex or glob was rejected (including ReDoS guards). |
| 401 | unauthenticated |
Missing or invalid Bearer token. |
| 402 | limit_exceeded |
A tier limit was hit; limit names it. Nothing was deleted; reads keep working. |
| 403 | permission_denied |
You can see the target but lack the verb; action and path say which. |
| 404 | not_found |
The target does not exist — or you may not read it. |
| 404 | section_not_found |
The file exists but the section ref resolved to nothing. |
| 404 | unknown_op |
No operation by that name. |
| 500 | internal |
Server fault; nothing about the cause is leaked. |
No existence leak. Reads you are not permitted return 404 not_found, never 403 — an unauthorized caller cannot distinguish "hidden" from "absent". 403 permission_denied appears only where existence is already known, such as writing to a path you can read.
Validation. Every input is zod-validated on every surface. Paths are normalized (leading /, NFC, no dot segments); files end in .md; content is capped at 512 KiB per file.
Reference#
add_comment#
Add a comment anchored to a section of a markdown file (sectionRef: slug path, ordinal, or '' for the preamble), optionally pinned to a quoted text range. Requires comment permission on the path.
Permission: comment
| Parameter | Type | Required | Description |
|---|---|---|---|
libraryId |
string | yes | — |
path |
string | yes | — |
sectionRef |
string | yes | — |
body |
string | yes | — |
textRange |
object | no | — |
add_org_member#
Add a principal to an org as admin or member; org-subject grants apply to them immediately. Requires being the org's owner or an admin member (manage_org).
Permission: manage_org
| Parameter | Type | Required | Description |
|---|---|---|---|
orgId |
string | yes | — |
principalId |
string | yes | — |
role |
"admin" \ | "member" | yes |
archive_comment#
Archive (soft-remove) a comment by id. Requires comment permission on the path, plus being the comment's author or holding manage_grants there.
Permission: comment
| Parameter | Type | Required | Description |
|---|---|---|---|
libraryId |
string | yes | — |
path |
string | yes | — |
commentId |
string | yes | — |
create_agent#
Create an agent identity owned by the calling principal; API keys can then be minted for it from the account page. Subject to the account's agent tier limit; requires no library permission.
Permission: manage_principals
| Parameter | Type | Required | Description |
|---|---|---|---|
displayName |
string | yes | — |
create_folder#
Create a folder at path (must not end in .md). Missing parent folders are created. Requires create_folder permission on the path.
Permission: create_folder
| Parameter | Type | Required | Description |
|---|---|---|---|
libraryId |
string | yes | — |
path |
string | yes | — |
create_grant#
Grant a principal, org, or the public access to a library path prefix ('/' = whole library, '' = unscoped writer rule), via either a role (reader, writer, admin) or an explicit action list — provide exactly one of role or actions. Requires manage_grants permission on the path prefix.
Permission: manage_grants
| Parameter | Type | Required | Description |
|---|---|---|---|
libraryId |
string | yes | — |
subject |
object \ | object \ | object |
pathPrefix |
string | yes | — |
role |
"reader" \ | "writer" \ | "admin" |
actions |
array | no | — |
create_library#
Create a new library owned by the calling principal. Everyone may create libraries they own, subject to the account's library tier limit.
Permission: create_library
| Parameter | Type | Required | Description |
|---|---|---|---|
name |
string | yes | — |
create_org#
Create an org owned by you; you become its first admin member. Orgs can own libraries and be grant subjects. Requires the team tier.
Permission: manage_org
| Parameter | Type | Required | Description |
|---|---|---|---|
name |
string | yes | — |
delete_library#
Soft-delete an entire library; its contents become invisible to all ops. Requires delete permission on the library root.
Permission: delete
| Parameter | Type | Required | Description |
|---|---|---|---|
libraryId |
string | yes | — |
delete_node#
Soft-delete the file or folder at path; folders delete their entire subtree. Returns the number of nodes deleted. Requires delete permission on the path.
Permission: delete
| Parameter | Type | Required | Description |
|---|---|---|---|
libraryId |
string | yes | — |
path |
string | yes | — |
get_audit_log#
Read a library's audit log, newest first (who did what, when, on which path), up to limit entries (default 50, max 200). Optional filters: actorId (one principal), action (exact, e.g. write_file), pathPrefix (entries at or under a path), before (only entries older than this epoch-millis timestamp — use for paging). Requires view_audit permission on the library.
Permission: view_audit
| Parameter | Type | Required | Description |
|---|---|---|---|
libraryId |
string | yes | — |
actorId |
string | no | — |
action |
string | no | — |
pathPrefix |
string | no | — |
limit |
integer | no | — |
before |
integer | no | — |
get_usage#
Read a library's usage: live file, folder, and byte counts plus the owner's tier limits for documents and storage (and the owner's agent count for personal libraries). Requires view_stats permission on the library.
Permission: view_stats
| Parameter | Type | Required | Description |
|---|---|---|---|
libraryId |
string | yes | — |
list_comments#
List the comments on a markdown file, oldest first; archived comments are excluded unless includeArchived is true. Requires read permission on the path.
Permission: read
| Parameter | Type | Required | Description |
|---|---|---|---|
libraryId |
string | yes | — |
path |
string | yes | — |
includeArchived |
boolean | no | — |
list_grants#
List the active (non-revoked) grants of a library. Requires manage_grants permission on the library root.
Permission: manage_grants
| Parameter | Type | Required | Description |
|---|---|---|---|
libraryId |
string | yes | — |
list_libraries#
List the libraries visible to the caller: libraries they own plus libraries where a grant names them. No permission needed beyond authentication.
Permission: read
No parameters — send {}.
list_org_members#
List an org's members with their roles. Available to the org's members only; anyone else gets not_found.
Permission: manage_org
| Parameter | Type | Required | Description |
|---|---|---|---|
orgId |
string | yes | — |
list_sections#
List the heading sections of a markdown file: slug path, ordinal, rank, and title for each, in document order. Requires read permission on the path.
Permission: read
| Parameter | Type | Required | Description |
|---|---|---|---|
libraryId |
string | yes | — |
path |
string | yes | — |
list_shares#
List the active shares (non-revoked grants) scoped at or under a path ('/' when omitted). Requires share permission on that path.
Permission: share
| Parameter | Type | Required | Description |
|---|---|---|---|
libraryId |
string | yes | — |
path |
string | no | — |
list_tree#
List the files and folders of a library, optionally under a path prefix and limited to a depth below it. Returns node metadata without file content, sorted by path. Requires read permission; nodes you cannot read are omitted.
Permission: read
| Parameter | Type | Required | Description |
|---|---|---|---|
libraryId |
string | yes | — |
prefix |
string | no | — |
depth |
integer | no | — |
move_node#
Move or rename a file or folder from fromPath to toPath; folders move with their entire subtree. Requires write and delete permission on fromPath and write permission on toPath.
Permission: write
| Parameter | Type | Required | Description |
|---|---|---|---|
libraryId |
string | yes | — |
fromPath |
string | yes | — |
toPath |
string | yes | — |
read_file#
Read the markdown file at path, returning its full content plus metadata (title, revision, size). Requires read permission on the path.
Permission: read
| Parameter | Type | Required | Description |
|---|---|---|---|
libraryId |
string | yes | — |
path |
string | yes | — |
read_section#
Read one section of a markdown file by ref — a slug path like 'getting-started/install', an ordinal like '4.2', or '' for the preamble — returning its raw markdown including subsections, plus the document's full section listing. Requires read permission on the path.
Permission: read
| Parameter | Type | Required | Description |
|---|---|---|---|
libraryId |
string | yes | — |
path |
string | yes | — |
ref |
string | yes | — |
remove_org_member#
Remove a member from an org (the owner cannot be removed); org-subject grants stop applying to them immediately. Requires being the org's owner or an admin member (manage_org).
Permission: manage_org
| Parameter | Type | Required | Description |
|---|---|---|---|
orgId |
string | yes | — |
principalId |
string | yes | — |
replace_in_section#
Apply a regex find-and-replace inside one section of a markdown file (ref: slug path, ordinal, or '' for the preamble). Returns the updated node and the match count; zero matches leaves the file untouched. Requires write permission on the path.
Permission: write
| Parameter | Type | Required | Description |
|---|---|---|---|
libraryId |
string | yes | — |
path |
string | yes | — |
ref |
string | yes | — |
pattern |
string | yes | — |
flags |
string | no | — |
replacement |
string | yes | — |
replace_section#
Replace the body of a section of a markdown file (ref: slug path, ordinal, or '' for the preamble). The section's own heading line is KEPT and newContent becomes everything beneath it, including any subsections. Note that read_section returns the heading line as well, so passing its output straight back would duplicate the heading — send only the text below it. The rest of the document stays byte-identical. Requires write permission on the path.
Permission: write
| Parameter | Type | Required | Description |
|---|---|---|---|
libraryId |
string | yes | — |
path |
string | yes | — |
ref |
string | yes | — |
newContent |
string | yes | — |
revoke_grant#
Revoke a grant by id; it stops applying immediately. Requires manage_grants permission on the grant's path prefix.
Permission: manage_grants
| Parameter | Type | Required | Description |
|---|---|---|---|
grantId |
string | yes | — |
revoke_share#
Revoke a share by its grant id; access stops immediately. Requires share (or manage_grants) permission on the share's path.
Permission: share
| Parameter | Type | Required | Description |
|---|---|---|---|
grantId |
string | yes | — |
search#
Search a library's markdown files. mode=glob matches file paths by glob pattern (query "**/*.md"); mode=grep scans file content with a regular expression (query "TODO\s+urgent"); mode=boolean AND-matches whitespace-separated terms with uppercase OR between groups, -term negation, and "quoted phrases" (query "incident OR postmortem -draft"); mode=semantic ranks files by meaning using vector embeddings (Pro and Team tiers, hits carry a score). Optional pathPrefix restricts the search to that subtree. Returns hits with path, enclosing section reference, snippet, and line number. Requires read permission; files you cannot read are never scanned or revealed.
Permission: read
| Parameter | Type | Required | Description |
|---|---|---|---|
libraryId |
string | yes | — |
query |
string | yes | — |
mode |
"glob" \ | "grep" \ | "boolean" \ |
pathPrefix |
string | no | — |
limit |
integer | no | — |
set_org_member_role#
Change an org member's role between admin and member. Requires being the org's owner or an admin member (manage_org).
Permission: manage_org
| Parameter | Type | Required | Description |
|---|---|---|---|
orgId |
string | yes | — |
principalId |
string | yes | — |
role |
"admin" \ | "member" | yes |
share_node#
Share a file or folder subtree with a principal, an org, an email (resolved to an existing account), or the public, at an access level: view (read), comment (read + comment), or edit (read + comment + write). Public shares appear at /share/{libraryId}{path}. Requires share permission on the path.
Permission: share
| Parameter | Type | Required | Description |
|---|---|---|---|
libraryId |
string | yes | — |
path |
string | yes | — |
subject |
object \ | object \ | object \ |
access |
"view" \ | "comment" \ | "edit" |
write_file#
Create or overwrite a markdown file at path (must end in .md). Missing parent folders are created. Requires write permission on the path.
Permission: write
| Parameter | Type | Required | Description |
|---|---|---|---|
libraryId |
string | yes | — |
path |
string | yes | — |
content |
string | yes | — |