Download OpenAPI specification:
REST API for Granite clients, bots, and integrations.
Conventions (apply to every operation; see PLAN.md 3.2 and 3.6):
https://api.granite.md. All public operations live under /v1.
After Phase 6 ships, /v1 changes are additive only.application/problem+json, schema Problem).
The type URI is https://granite.md/problems/<slug>; code refines it for programmatic handling.
Every response carries X-Request-ID, also echoed as request_id in problems.cursor and limit and return
{ "items": [...], "next_cursor": "..." }. next_cursor is absent on the last page.
Cursors are opaque; clients must not parse or build them.POST operations accept an Idempotency-Key header
(1-255 printable ASCII). Repeating a request with the same key and body within 24 hours
returns the original response; the same key with a different body returns 409 with
code idempotency_key_reused.Authorization: Bearer <token> with a session access token,
a personal API token (gr_pat_...), or an OAuth access token. Scopes are listed per operation.429 with code token_rate_limited and a Retry-After header (seconds).Crash and error reports from the apps (PLAN.md P5-T01), written to the server log for the on-call person. No sign-in is needed (an app can fail before it). Reports must not contain note text, file names, or anything the person typed. Limited per address.
| kind required | string Enum: "crash" "error" "render" |
| message required | string <= 1000 characters |
| stack | string <= 8000 characters |
| screen | string <= 200 characters |
| platform required | string Enum: "web" "macos" "windows" "linux" "ios" "android" "cli" "other" |
| app_version required | string <= 50 characters |
| os_version | string <= 50 characters |
{- "kind": "crash",
- "message": "string",
- "stack": "string",
- "screen": "string",
- "platform": "web",
- "app_version": "string",
- "os_version": "string"
}{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Creates an unverified account and emails a verification link, or with confirm: code
(the mobile apps) a 6-digit code to send to POST /v1/auth/signup/confirm. The response
is the same whether or not the email is already registered: a verified account's owner
is notified instead, and an account not yet confirmed gets a new link or code (earlier
ones stop working) whose confirmation also sets this request's password and name.
| email required | string <email> <= 254 characters |
| password required | string [ 10 .. 256 ] characters Must also be hard to guess: passwords built from common words, the person's name or email, dates, repeats, or keyboard runs are refused (field "password"). |
| name | string <= 200 characters |
| workspace_name | string [ 1 .. 100 ] characters Signs up for a business account: a new account also gets a workspace of this name, owned by it, on the 30-day Business trial. Ignored when the email already has an account. |
| confirm | string (EmailConfirmMode) Enum: "link" "code" How the email proves the address: a link to open ( |
{- "password": "stringstri",
- "name": "string",
- "workspace_name": "string",
- "confirm": "link"
}{- "status": "accepted"
}Confirms the email address with the 6-digit code from a confirm: code sign-up (or
resend) and signs in on this device in the same step, so the password is not typed
again. A code works once, for 15 minutes, and stops working after 5 wrong tries. A
wrong, expired, or used-up code and an unknown email all answer 400 with code
invalid_signup_code.
| email required | string <email> <= 254 characters |
| code required | string <= 20 characters The 6 digits from the email. |
required | object (DeviceInfo) |
{- "code": "string",
- "device": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "Fuad's MacBook",
- "platform": "web",
- "app_version": "string"
}
}{- "access_token": "string",
- "token_type": "Bearer",
- "expires_in": 0,
- "refresh_token": "string",
- "refresh_expires_in": 0,
- "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
- "user": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "email_verified": true,
- "two_factor_enabled": true,
- "created_at": "2019-08-24T14:15:22Z",
- "avatar_url": "string"
}
}| token required | string <= 200 characters |
{- "token": "string"
}{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Sends a new link, or with confirm: code a new 6-digit code (earlier codes stop
working). Always answers 202, whether or not the email has an unverified account.
| email required | string <email> <= 254 characters |
| confirm | string (EmailConfirmMode) Enum: "link" "code" How the email proves the address: a link to open ( |
{- "confirm": "link"
}{- "status": "accepted"
}Checks the password and starts a session for the device. After repeated failures the email is locked for a while (429), whether or not it has an account.
| email required | string <email> <= 254 characters |
| password required | string <= 256 characters |
required | object (DeviceInfo) |
{- "password": "string",
- "device": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "Fuad's MacBook",
- "platform": "web",
- "app_version": "string"
}
}{- "access_token": "string",
- "token_type": "Bearer",
- "expires_in": 0,
- "refresh_token": "string",
- "refresh_expires_in": 0,
- "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
- "user": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "email_verified": true,
- "two_factor_enabled": true,
- "created_at": "2019-08-24T14:15:22Z",
- "avatar_url": "string"
}
}Finds the workspace that verified the email's domain and set up SSO, and returns the
identity provider's sign-in URL. Open it in the browser; the provider returns to the
web app's /sso/callback, which finishes with POST /v1/auth/sso/finish.
With client=mobile (the phone app, which opens the page in the system browser), the
state (OpenID Connect) or handoff code (SAML) starts with app.: the web callback
then hands it to the phone app in a granite://sso-callback link instead of finishing
itself, and the app finishes.
| client | string Enum: "web" "mobile" Who finishes the sign-in; |
| email required | string <= 320 characters |
{- "email": "string"
}{- "authorize_url": "string"
}Exchanges the code from the identity provider and starts a session. People new to the workspace join it with the connection's role. Two-step verification is left to the identity provider.
| state | string <= 200 characters |
| code | string <= 4000 characters |
| handoff | string <= 200 characters |
required | object (DeviceInfo) |
{- "state": "string",
- "code": "string",
- "handoff": "string",
- "device": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "Fuad's MacBook",
- "platform": "web",
- "app_version": "string"
}
}{- "access_token": "string",
- "token_type": "Bearer",
- "expires_in": 0,
- "refresh_token": "string",
- "refresh_expires_in": 0,
- "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
- "user": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "email_verified": true,
- "two_factor_enabled": true,
- "created_at": "2019-08-24T14:15:22Z",
- "avatar_url": "string"
}
}Exchanges a refresh token for a new access token and a new refresh token. Each refresh
token works once; presenting a used one ends every session of that sign-in
(code refresh_token_reused). Clients must not refresh concurrently.
| refresh_token required | string <= 200 characters |
{- "refresh_token": "string"
}{- "access_token": "string",
- "token_type": "Bearer",
- "expires_in": 0,
- "refresh_token": "string",
- "refresh_expires_in": 0,
- "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
- "user": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "email_verified": true,
- "two_factor_enabled": true,
- "created_at": "2019-08-24T14:15:22Z",
- "avatar_url": "string"
}
}{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Emails a reset link, or with confirm: code (the mobile apps) a 6-digit code for
POST /v1/auth/password-reset/code/confirm (earlier codes stop working). Always
answers 202, whether or not the email has an account.
| email required | string <email> <= 254 characters |
| confirm | string (EmailConfirmMode) Enum: "link" "code" How the email proves the address: a link to open ( |
{- "confirm": "link"
}{- "status": "accepted"
}Sets the password from a reset link and signs out every device.
| token required | string <= 200 characters |
| password required | string [ 10 .. 256 ] characters Must also be hard to guess: passwords built from common words, the person's name or email, dates, repeats, or keyboard runs are refused (field "password"). |
{- "token": "string",
- "password": "stringstri"
}{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Says whether a reset code is right before the person chooses a new password. The code
is not used up; a wrong one counts as one of its 5 tries. A wrong, expired, or used-up
code and an unknown email all answer 400 with code invalid_reset_code.
| email required | string <email> <= 254 characters |
| code required | string <= 20 characters The 6 digits from the email. |
{- "code": "string"
}{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Sets the new password with the 6-digit code from a confirm: code reset request, signs
out every other session, and signs in on this device. Accounts with two-step
verification get a challenge to finish with POST /v1/auth/login/2fa, as at sign-in.
A code works once, for 15 minutes, and stops working after 5 wrong tries; failures
answer 400 with code invalid_reset_code.
| email required | string <email> <= 254 characters |
| code required | string <= 20 characters The 6 digits from the email. |
| password required | string [ 10 .. 256 ] characters Must also be hard to guess: passwords built from common words, the person's name or email, dates, repeats, or keyboard runs are refused (field "password"). |
required | object (DeviceInfo) |
{- "code": "string",
- "password": "stringstri",
- "device": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "Fuad's MacBook",
- "platform": "web",
- "app_version": "string"
}
}{- "access_token": "string",
- "token_type": "Bearer",
- "expires_in": 0,
- "refresh_token": "string",
- "refresh_expires_in": 0,
- "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
- "user": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "email_verified": true,
- "two_factor_enabled": true,
- "created_at": "2019-08-24T14:15:22Z",
- "avatar_url": "string"
}
}Send either code (from the authenticator app) or recovery_code. Each works once.
| mfa_token required | string <= 2000 characters |
| code | string <= 10 characters |
| recovery_code | string <= 40 characters |
{- "mfa_token": "string",
- "code": "string",
- "recovery_code": "string"
}{- "access_token": "string",
- "token_type": "Bearer",
- "expires_in": 0,
- "refresh_token": "string",
- "refresh_expires_in": 0,
- "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
- "user": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "email_verified": true,
- "two_factor_enabled": true,
- "created_at": "2019-08-24T14:15:22Z",
- "avatar_url": "string"
}
}Re-checks the password (and the authenticator code when two-factor authentication is on).
For the next 10 minutes this session may change two-factor settings. Other sensitive
actions answer 403 with code step_up_required until this is done.
| password required | string <= 256 characters |
| code | string <= 10 characters Authenticator code, required when two-factor authentication is on. |
{- "password": "string",
- "code": "string"
}{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}For the desktop app's sign-in through the browser (Google, single sign-on). The app opens
the web app with a PKCE challenge; once signed in, the web app calls this and passes the
one-time code to the app in a granite://auth link. The app redeems it with
POST /v1/auth/app-handoff/finish. Needs a session, not an API token. A session from
single sign-on hands the app a single sign-on session for the same workspace.
| code_challenge required | string = 43 characters base64url(SHA-256(code_verifier)) without padding (RFC 7636 S256). |
{- "code_challenge": "stringstringstringstringstringstringstrings"
}{- "code": "string",
- "expires_in": 0
}Exchanges the one-time code from POST /v1/auth/app-handoff and the app's PKCE verifier
for a session on the app's device. A code works once, also when the verifier is wrong.
| code required | string <= 200 characters |
| code_verifier required | string [ 43 .. 128 ] characters |
required | object (DeviceInfo) |
{- "code": "string",
- "code_verifier": "stringstringstringstringstringstringstrings",
- "device": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "Fuad's MacBook",
- "platform": "web",
- "app_version": "string"
}
}{- "access_token": "string",
- "token_type": "Bearer",
- "expires_in": 0,
- "refresh_token": "string",
- "refresh_expires_in": 0,
- "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
- "user": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "email_verified": true,
- "two_factor_enabled": true,
- "created_at": "2019-08-24T14:15:22Z",
- "avatar_url": "string"
}
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "email_verified": true,
- "two_factor_enabled": true,
- "created_at": "2019-08-24T14:15:22Z",
- "avatar_url": "string"
}| name required | string <= 200 characters |
{- "name": "string"
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "email_verified": true,
- "two_factor_enabled": true,
- "created_at": "2019-08-24T14:15:22Z",
- "avatar_url": "string"
}Needs a recent password check (POST /v1/auth/step-up). The account is anonymized at
once and signed out everywhere; its personal vaults are purged within the hour, then
the account itself. Workspaces you own alone are deleted too; owning one with other
members is refused (workspace_owner): transfer it or delete it first. A company account
(an admin or member of a workspace) belongs to the organization and is refused
(company_account): the workspace's owner or an admin deletes it. Encrypted backups age
out within 35 days.
{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Pro and Business: a zip with account.json (profile, devices, API tokens, workspaces,
appearance preferences) and each personal vault as a folder of plain files under Vaults/. Free (the right of
access and portability): the same data as one JSON document (format
granite-data/1), each file's content inline, as UTF-8 text or base64.
A PNG or JPEG of up to 512 KB and 2048 pixels on a side (the apps send 256 x 256); it
replaces the previous photo, which stops being served. 400 invalid_avatar otherwise.
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "email_verified": true,
- "two_factor_enabled": true,
- "created_at": "2019-08-24T14:15:22Z",
- "avatar_url": "string"
}{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}No sign-in: pages cannot send a token with an image, so the random id (new with every upload) is what keeps photos from being listed. Cached for a year; a new photo has a new id.
| avatar_id required | string^[A-Za-z0-9_-]{22}$ |
{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Per kind, whether an email goes out and whether phones get a push alert, the same on every device. Being added to a team always notifies by email and push, so it is not here. Everything is on until changed.
{- "email": {
- "comment": true,
- "share": true,
- "mention": true,
- "resolved": true
}, - "push": {
- "comment": true,
- "share": true,
- "mention": true,
- "resolved": true
}
}Replaces all of them at once. In-app notifications (the bell) always arrive.
required | object (NotificationChannels) One switch per kind. |
required | object (NotificationChannels) One switch per kind. |
{- "email": {
- "comment": true,
- "share": true,
- "mention": true,
- "resolved": true
}, - "push": {
- "comment": true,
- "share": true,
- "mention": true,
- "resolved": true
}
}{- "email": {
- "comment": true,
- "share": true,
- "mention": true,
- "resolved": true
}, - "push": {
- "comment": true,
- "share": true,
- "mention": true,
- "resolved": true
}
}Theme, editor font and size, readable width and live preview, the same on every device
you sign in on. Without saved preferences, the defaults (and no updated_at).
Keyboard settings (vim, hotkeys, the formatting bar) stay on each device and are not here.
{- "theme": "system",
- "editor_font": "sans",
- "font_size": 15,
- "readable_width": true,
- "live_preview": true,
- "line_numbers": true,
- "updated_at": "2019-08-24T14:15:22Z"
}Replaces all of them at once (updated_at is set by the server and ignored here). 400
with the invalid fields for an unknown theme or font, or a font size outside 12-24.
| theme required | string Default: "system" Enum: "system" "light" "dark" |
| editor_font required | string Default: "sans" Enum: "sans" "mono" |
| font_size required | integer [ 12 .. 24 ] Default: 15 |
| readable_width required | boolean Default: true Keep lines to a comfortable width instead of the full window. |
| live_preview required | boolean Default: true Render Markdown while editing; false shows the raw Markdown. |
| line_numbers | boolean Default: true Number the lines beside notes. Optional when saving (an app that leaves it out keeps the saved value). |
{- "theme": "system",
- "editor_font": "sans",
- "font_size": 15,
- "readable_width": true,
- "live_preview": true,
- "line_numbers": true
}{- "theme": "system",
- "editor_font": "sans",
- "font_size": 15,
- "readable_width": true,
- "live_preview": true,
- "line_numbers": true,
- "updated_at": "2019-08-24T14:15:22Z"
}Requires a recent step-up (POST /v1/auth/step-up). Signs out every other device.
| password required | string [ 10 .. 256 ] characters Must also be hard to guess: passwords built from common words, the person's name or email, dates, repeats, or keyboard runs are refused (field "password"). |
{- "password": "stringstri"
}{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Devices that have not been signed out, most recently used first. The plan limits how
many may be signed in at once; signing in on another one answers 403 with code
device_limit_reached until a device is signed out here.
{- "items": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "platform": "web",
- "app_version": "string",
- "last_seen_at": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z",
- "active_sessions": 0,
- "current": true
}
]
}{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}| device_id required | string <uuid> |
| name required | string [ 1 .. 100 ] characters |
{- "name": "string"
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "platform": "web",
- "app_version": "string",
- "last_seen_at": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z",
- "active_sessions": 0,
- "current": true
}Its sessions end; its access tokens stop working within 30 seconds.
| device_id required | string <uuid> |
{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Tokens that are not revoked. Token values are never shown again.
{- "items": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "prefix": "string",
- "scopes": [
- "vaults:read"
], - "expires_at": "2019-08-24T14:15:22Z",
- "last_used_at": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z"
}
]
}Requires a signed-in session with a recent step-up (POST /v1/auth/step-up); tokens
cannot create tokens. The value (gr_pat_ + 36 characters, the last 6 a checksum) is
returned only in this response. The plan limits how many tokens may be active (403
plan_limit_api_tokens). Send it as Authorization: Bearer <token>.
| name required | string [ 1 .. 100 ] characters |
| scopes required | Array of strings (APITokenScope) non-empty Items Enum: "vaults:read" "vaults:write" "sync" "kb:query" "notes:create" "notes:edit" "folders:create" "folders:edit" "templates:edit" |
| expires_in_days | integer [ 1 .. 3650 ] Omitted means the token does not expire. |
{- "name": "string",
- "scopes": [
- "vaults:read"
], - "expires_in_days": 1
}{- "token": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "prefix": "string",
- "scopes": [
- "vaults:read"
], - "expires_at": "2019-08-24T14:15:22Z",
- "last_used_at": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z"
}, - "value": "string"
}The token stops working at once.
| token_id required | string <uuid> |
{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Public reference data: what each plan includes, for upgrade prompts (which plan adds
an integration, for example). Your own plan is in GET /v1/me/entitlements.
{- "items": [
- {
- "key": "free",
- "name": "string",
- "monthly_price_cents": 0,
- "per_seat": true,
- "limits": {
- "synced_vaults": 0,
- "storage_bytes": 0,
- "max_file_bytes": 0,
- "synced_devices": 0,
- "version_history_days": 0,
- "remote_mcp": true,
- "api_tokens": 0,
- "knowledge_base": true,
- "live_coediting": "own_devices",
- "drive_references": "none",
- "guests_per_vault": 0,
- "published_notes": 0,
- "workspaces": true,
- "sso": true,
- "audit_log": true,
- "webhooks": true,
- "integrations": [
- "slack"
], - "integrations_per_vault": 0,
- "note_sharing": true,
- "data_export": true
}
}
]
}The single source of plan limits for clients (PLAN.md 1.2). Null means unlimited. An
account is personal (Free or Pro) or a company account: a member above Guest of one
workspace, with that workspace's plan (plan.company).
{- "plan": {
- "key": "free",
- "name": "string",
- "company": {
- "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
- "workspace_name": "string"
}
}, - "limits": {
- "synced_vaults": 0,
- "storage_bytes": 0,
- "max_file_bytes": 0,
- "synced_devices": 0,
- "version_history_days": 0,
- "remote_mcp": true,
- "api_tokens": 0,
- "knowledge_base": true,
- "live_coediting": "own_devices",
- "drive_references": "none",
- "guests_per_vault": 0,
- "published_notes": 0,
- "workspaces": true,
- "sso": true,
- "audit_log": true,
- "webhooks": true,
- "integrations": [
- "slack"
], - "integrations_per_vault": 0,
- "note_sharing": true,
- "data_export": true
}, - "usage": {
- "synced_vaults": 0,
- "storage_bytes": 0
}
}Which features are turned on for the signed-in user (PLAN.md Appendix G.2). Apps read this after sign-in and hide features whose flag is off or missing. A flag stays on or off for a user while its rollout grows.
{- "flags": {
- "editor.new_toolbar": true
}
}{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Turns two-factor authentication on and returns recovery codes, shown only once.
| code required | string <= 10 characters |
{- "code": "string"
}{- "recovery_codes": [
- "string"
]
}Saves this device's APNs or FCM token (the mobile apps, PLAN.md P5-T06). The device gets alerts for mentions and shares, and silent "sync now" nudges when a vault it can use changes elsewhere. Only a signed-in app can do this, not an API token: 403. A token moves to the device that saved it last.
| provider required | string Enum: "apns" "fcm" apns on iPhone and iPad, fcm on Android. |
| token required | string [ 1 .. 4096 ] characters |
| sandbox | boolean Default: false An APNs token from a development build (Apple's sandbox gateway). |
{- "provider": "apns",
- "token": "string",
- "sandbox": false
}{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Stores you connected to Granite with the Granite for Shopify app, and stores connected to workspaces you administer. Each store's notes are in its vault.
{- "items": [
- {
- "shop_domain": "string",
- "shop_name": "string",
- "status": "installed",
- "connected": true,
- "vault_id": "432b199b-1f71-42bf-ba0b-33d512afa9de",
- "owner_type": "user",
- "connected_at": "2019-08-24T14:15:22Z"
}
]
}The store stops syncing; its vault and notes stay where they are.
| shop_domain required | string <= 255 characters |
{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}The store behind a connect link and the accounts you may connect it to: your own, or a
workspace you own or administer. Codes work for 15 minutes (404 shopify_link_invalid).
| code required | string <= 100 characters The one-time code from the link the app in Shopify opened. |
{- "shop_domain": "string",
- "shop_name": "string",
- "owners": [
- {
- "type": "user",
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "plan": "string"
}
], - "connected_to": "string"
}Connects the store to the chosen account and creates the vault "
| code required | string <= 100 characters The one-time code from the link the app in Shopify opened. |
| owner_type required | string Enum: "user" "workspace" |
| owner_id required | string <uuid> |
{- "owner_type": "user",
- "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05"
}{- "shop_domain": "string",
- "shop_name": "string",
- "status": "installed",
- "connected": true,
- "vault_id": "432b199b-1f71-42bf-ba0b-33d512afa9de",
- "owner_type": "user",
- "connected_at": "2019-08-24T14:15:22Z"
}| cursor | string <= 512 characters Opaque cursor from a previous page's |
| limit | integer <int32> [ 1 .. 200 ] Default: 50 Maximum items to return. |
| trash | boolean Default: false List deleted vaults that can still be restored instead of active ones. |
{- "items": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_at": "2019-08-24T14:15:22Z",
- "purge_after": "2019-08-24T14:15:22Z"
}
], - "next_cursor": "string"
}| name required | string [ 1 .. 100 ] characters |
| workspace_id | string <uuid> Create a shared vault in this workspace (members and above) instead of a personal one. |
{- "name": "string",
- "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9"
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_at": "2019-08-24T14:15:22Z",
- "purge_after": "2019-08-24T14:15:22Z"
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_at": "2019-08-24T14:15:22Z",
- "purge_after": "2019-08-24T14:15:22Z"
}| vault_id required | string <uuid> |
| name required | string [ 1 .. 100 ] characters |
{- "name": "string"
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_at": "2019-08-24T14:15:22Z",
- "purge_after": "2019-08-24T14:15:22Z"
}The vault can be restored for 30 days (purge_after), then it is deleted permanently.
| vault_id required | string <uuid> |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_at": "2019-08-24T14:15:22Z",
- "purge_after": "2019-08-24T14:15:22Z"
}Every file you can read, at its path, exactly as synced (PLAN.md 5, Portability). Needs the vault owner's plan to include exports (Pro and Business; plan_limit_data_export otherwise).
| vault_id required | string <uuid> |
{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}| vault_id required | string <uuid> |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z",
- "deleted_at": "2019-08-24T14:15:22Z",
- "purge_after": "2019-08-24T14:15:22Z"
}Vault admins.
| vault_id required | string <uuid> |
{- "items": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "principal_type": "user",
- "principal_id": "b0fe3bdd-8201-445a-aab3-a018692d6aca",
- "access": "read",
- "folder": "string",
- "created_at": "2019-08-24T14:15:22Z"
}
]
}Vault admins of workspace vaults (inside a restricted folder, those who administer it; never inside a private folder). With folder, access applies to that folder or note only. Granting the same person or group and folder again changes the access. Guests can only read and comment.
| vault_id required | string <uuid> |
| principal_type required | string Enum: "user" "group" |
| principal_id required | string <uuid> |
| access required | string Enum: "read" "comment" "write" "admin" |
| folder | string <= 1024 characters |
{- "principal_type": "user",
- "principal_id": "b0fe3bdd-8201-445a-aab3-a018692d6aca",
- "access": "read",
- "folder": "string"
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "principal_type": "user",
- "principal_id": "b0fe3bdd-8201-445a-aab3-a018692d6aca",
- "access": "read",
- "folder": "string",
- "created_at": "2019-08-24T14:15:22Z"
}Vault admins. Applies from the next request.
| vault_id required | string <uuid> |
| grant_id required | string <uuid> |
{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Workspace owners and admins see all of them (private folders by name only); others see those they can open.
| vault_id required | string <uuid> |
{- "items": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "folder": "string",
- "private": true,
- "private_to": "ba469d7a-c1d2-41fd-a49e-f96862913789",
- "created_at": "2019-08-24T14:15:22Z"
}
]
}Workspace vaults (Business). Restricted (private false; owners and admins): only grants made at or below the path count inside it, so it opens only to the teams and people it is then shared with (and owners and admins). Private (private true; any member who can edit it): only the caller can open it, workspace owners and admins included; they still see that it exists and can lift it. Restricting the same path again changes its kind.
| vault_id required | string <uuid> |
| path required | string [ 1 .. 1024 ] characters |
| private required | boolean |
{- "path": "string",
- "private": true
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "folder": "string",
- "private": true,
- "private_to": "ba469d7a-c1d2-41fd-a49e-f96862913789",
- "created_at": "2019-08-24T14:15:22Z"
}A private folder's member, or workspace owners and admins. Applies from the next request.
| vault_id required | string <uuid> |
| restriction_id required | string <uuid> |
{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Anyone who can read the path. Says whether it is private or restricted and what the caller may change.
| vault_id required | string <uuid> |
| path required | string [ 1 .. 1024 ] characters |
{- "path": "string",
- "private": true,
- "restricted": true,
- "restricted_at": "string",
- "restriction": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "folder": "string",
- "private": true,
- "private_to": "ba469d7a-c1d2-41fd-a49e-f96862913789",
- "created_at": "2019-08-24T14:15:22Z"
}, - "can_manage": true,
- "can_make_private": true,
- "openers": [
- {
- "kind": "owner",
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "email": "string",
- "access": "read",
- "folder": "string",
- "members": 0,
- "grant_id": "a3c1da8e-13c6-4cab-955b-2120b58c2982"
}
]
}Google Drive references (PLAN.md Phase 11). A person connects their Google account (only the files they pick are visible to Granite), picks files, and each becomes a reference in a vault and a Markdown link in a note. Content is fetched from Google when read, converted in memory, and never stored. Everyone who can read the vault can read a referenced file through the connection of the person who added it.
Revokes Granite's access at Google. References stay as links; their content can no longer be read.
{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Returns Google's consent page. Google sends the person back to the app's /drive/callback, which finishes with POST /v1/drive/connect/finish. Needs Pro (403 plan_limit_drive).
With client=mobile (the phone app, which opens the page in the system browser), the
state starts with app.: the web callback then hands code and state to the phone app
in a granite://drive-callback link instead of finishing itself, and the app finishes.
| client | string Enum: "web" "mobile" Who finishes the sign-in; |
{
}| state required | string [ 1 .. 200 ] characters |
| code required | string [ 1 .. 2000 ] characters |
{- "state": "string",
- "code": "string"
}{- "available": true,
- "connected": true,
- "google_account": "string",
- "state": "ok",
- "connected_at": "2019-08-24T14:15:22Z"
}A short-lived access token for your connection, with the browser key and project number the picker needs. 409 drive_not_connected or drive_reconnect.
{- "access_token": "string",
- "expires_at": "2019-08-24T14:15:22Z",
- "api_key": "string",
- "app_id": "string"
}| vault_id required | string <uuid> |
{- "items": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "drive_file_id": "string",
- "title": "string",
- "mime_type": "string",
- "url": "string",
- "icon_url": "string",
- "modified_at": "2019-08-24T14:15:22Z",
- "size": 0,
- "state": "ok",
- "created_at": "2019-08-24T14:15:22Z"
}
]
}Editors only. Uses your connection; afterwards everyone who can read the vault can read the file through it.
| vault_id required | string <uuid> |
| drive_file_id required | string [ 1 .. 200 ] characters |
{- "drive_file_id": "string"
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "drive_file_id": "string",
- "title": "string",
- "mime_type": "string",
- "url": "string",
- "icon_url": "string",
- "modified_at": "2019-08-24T14:15:22Z",
- "size": 0,
- "state": "ok",
- "created_at": "2019-08-24T14:15:22Z"
}| vault_id required | string <uuid> |
| ref_id required | string <uuid> |
{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Fetched from Google now: Docs as Markdown, Sheets as CSV (the first sheet), Slides and
PDFs as text, text files as they are; at most 10 MB read and 2 MB of text returned.
404 drive_no_access, 409 drive_reconnect, 413 drive_too_large, 422 drive_unsupported.
| vault_id required | string <uuid> |
| ref_id required | string <uuid> |
{- "ref": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "drive_file_id": "string",
- "title": "string",
- "mime_type": "string",
- "url": "string",
- "icon_url": "string",
- "modified_at": "2019-08-24T14:15:22Z",
- "size": 0,
- "state": "ok",
- "created_at": "2019-08-24T14:15:22Z"
}, - "text": "string",
- "format": "markdown",
- "truncated": true
}Plans and payments (PLAN.md 1.2, Phase 7). A person buys Pro, with its first 30 days free
once per person; a workspace buys Business per seat (members above Guest, at least 2)
after its 30-day trial. Payments run through
Stripe Checkout and Stripe's customer portal. A failed payment keeps the plan for 7 days;
after that, or when a subscription ends, the owner is on Free's limits: nothing is
deleted, but uploads over the quota are refused. Pass workspace_id for a workspace's
billing (its owner and admins only).
The caller's, or with workspace_id the workspace's, which only its owner sees (403 billing_forbidden); a workspace has one billing for all its members.
| workspace_id | string <uuid> A workspace you own; omit for your own billing. |
{- "plan": "string",
- "plan_name": "string",
- "monthly_price_cents": 0,
- "per_seat": true,
- "status": "free",
- "trial_ends_at": "2019-08-24T14:15:22Z",
- "grace_until": "2019-08-24T14:15:22Z",
- "seats": 0,
- "storage_bytes": 0,
- "storage_limit_bytes": 0,
- "purchasable": true,
- "manageable": true,
- "pro_trial_days": 0,
- "subscription": {
- "provider": "stripe",
- "status": "string",
- "seats": 0,
- "current_period_end": "2019-08-24T14:15:22Z",
- "cancel_at_period_end": true
}, - "company": {
- "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
- "workspace_name": "string"
}
}Returns a Stripe Checkout page to open. Pro is for a person, Business for a workspace
(workspace_id). Pro starts with pro_trial_days free (30 for a person who never had
Pro or a Pro trial on any channel, else none); Business starts after the rest of the trial, with seats or the
members above Guest, whichever is more (at least 2). 409 subscription_exists when the
owner already has an active subscription on any channel (the message says where it is
managed), or 409 account_in_workspace for Pro when the account belongs to a workspace
(a company account has its workspace's plan); 503 billing_unavailable when payments are not set up.
| plan required | string Enum: "pro" "business" |
| workspace_id | string <uuid> |
| seats | integer <int64> [ 2 .. 10000 ] |
{- "plan": "pro",
- "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
- "seats": 2
}{
}Returns Stripe's customer portal. 404 no_billing_account before the first purchase. A workspace's billing is its owner's (403 billing_forbidden otherwise).
| workspace_id | string <uuid> |
{- "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9"
}{
}The app sends the StoreKit 2 signed transaction (JWS) after a purchase or restore; it
must carry the account's ID as appAccountToken. 403 purchase_not_yours when it
belongs to another account (or is already held by one); 400 invalid_purchase when the
signature does not lead to Apple. Store notifications keep it current afterwards.
| signed_transaction required | string [ 1 .. 20000 ] characters |
{- "signed_transaction": "string"
}{- "plan": "string",
- "plan_name": "string",
- "monthly_price_cents": 0,
- "per_seat": true,
- "status": "free",
- "trial_ends_at": "2019-08-24T14:15:22Z",
- "grace_until": "2019-08-24T14:15:22Z",
- "seats": 0,
- "storage_bytes": 0,
- "storage_limit_bytes": 0,
- "purchasable": true,
- "manageable": true,
- "pro_trial_days": 0,
- "subscription": {
- "provider": "stripe",
- "status": "string",
- "seats": 0,
- "current_period_end": "2019-08-24T14:15:22Z",
- "cancel_at_period_end": true
}, - "company": {
- "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
- "workspace_name": "string"
}
}The app sends the purchase token; it must have been bought with the account's ID as the obfuscated account ID. The server reads it from Google Play and acknowledges it.
| purchase_token required | string [ 1 .. 4096 ] characters |
{- "purchase_token": "string"
}{- "plan": "string",
- "plan_name": "string",
- "monthly_price_cents": 0,
- "per_seat": true,
- "status": "free",
- "trial_ends_at": "2019-08-24T14:15:22Z",
- "grace_until": "2019-08-24T14:15:22Z",
- "seats": 0,
- "storage_bytes": 0,
- "storage_limit_bytes": 0,
- "purchasable": true,
- "manageable": true,
- "pro_trial_days": 0,
- "subscription": {
- "provider": "stripe",
- "status": "string",
- "seats": 0,
- "current_period_end": "2019-08-24T14:15:22Z",
- "cancel_at_period_end": true
}, - "company": {
- "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
- "workspace_name": "string"
}
}| workspace_id | string <uuid> A workspace you own; omit for your own billing. |
{- "items": [
- {
- "id": "string",
- "number": "string",
- "created_at": "2019-08-24T14:15:22Z",
- "total_cents": 0,
- "currency": "string",
- "status": "string",
- "url": "string",
- "pdf_url": "string"
}
]
}The cards saved with Stripe, the default first. None before the first purchase or card.
| workspace_id | string <uuid> A workspace you own; omit for your own billing. |
{- "items": [
- {
- "id": "string",
- "brand": "string",
- "last4": "string",
- "exp_month": 0,
- "exp_year": 0,
- "default": true
}
]
}Returns Stripe's hosted page for saving a card (Checkout in setup mode); nothing is
charged. The card becomes the default when there was none. 503 billing_unavailable
when payments are not set up; 403 billing_forbidden for a workspace you do not own.
| workspace_id | string <uuid> |
{- "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9"
}{
}409 card_needed for the default card while a subscription is paid with it and no other
card is saved; 404 no_such_card for a card that is not the owner's.
| payment_method_id required | string [ 1 .. 255 ] characters Stripe's ID of the card (pm_...). |
| workspace_id | string <uuid> A workspace you own; omit for your own billing. |
{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Makes the card the default for future invoices, including the current subscription's.
| payment_method_id required | string [ 1 .. 255 ] characters Stripe's ID of the card (pm_...). |
| workspace_id | string <uuid> |
{- "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9"
}{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Live files as of at (default: the current head). Pass the same at with cursor to get
later pages of the same snapshot (Appendix B.3).
| vault_id required | string <uuid> |
| at | integer <int64> >= 0 |
| cursor | string <= 512 characters Opaque cursor from a previous page's |
| limit | integer <int32> [ 1 .. 200 ] Default: 50 Maximum items to return. |
{- "head_seq": 0,
- "files": [
- {
- "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
- "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
- "path": "string",
- "blob_hash": "string",
- "size": 0,
- "content_type": "string",
- "kind": "markdown",
- "client_mtime": "2019-08-24T14:15:22Z"
}
], - "next_cursor": "string"
}Answers 410 with code cursor_expired when since is older than the kept log.
| vault_id required | string <uuid> |
| since required | integer <int64> >= 0 |
| limit | integer [ 1 .. 1000 ] Default: 500 |
{- "changes": [
- {
- "seq": 0,
- "op": "put",
- "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
- "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
- "path": "string",
- "old_path": "string",
- "blob_hash": "string",
- "size": 0,
- "content_type": "string",
- "kind": "markdown",
- "deleted": true,
- "author_id": "78424c75-5c41-4b25-9735-3c9f7d05c59e",
- "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
- "committed_at": "2019-08-24T14:15:22Z",
- "client_mtime": "2019-08-24T14:15:22Z"
}
], - "head_seq": 0,
- "has_more": true
}Anyone who can read the note. created_by is absent once history no longer reaches the first version.
| vault_id required | string <uuid> |
| file_id required | string <uuid> |
{- "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
- "path": "string",
- "created_at": "2019-08-24T14:15:22Z",
- "created_by": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "email": "string",
- "name": "string"
}, - "modified_at": "2019-08-24T14:15:22Z",
- "modified_by": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "email": "string",
- "name": "string"
}, - "size": 0,
- "versions": 0,
- "access": {
- "path": "string",
- "private": true,
- "restricted": true,
- "restricted_at": "string",
- "restriction": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "folder": "string",
- "private": true,
- "private_to": "ba469d7a-c1d2-41fd-a49e-f96862913789",
- "created_at": "2019-08-24T14:15:22Z"
}, - "can_manage": true,
- "can_make_private": true,
- "openers": [
- {
- "kind": "owner",
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "email": "string",
- "access": "read",
- "folder": "string",
- "members": 0,
- "grant_id": "a3c1da8e-13c6-4cab-955b-2120b58c2982"
}
]
}, - "shared_with": [
- "string"
]
}| vault_id required | string <uuid> |
| Idempotency-Key | string [ 1 .. 255 ] characters ^[\x21-\x7E]+$ Makes a non-idempotent POST safe to retry. See the conventions above. |
| device_id | string <uuid> |
required | Array of objects (CommitOp) <= 1000 items |
{- "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
- "ops": [
- {
- "type": "put",
- "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
- "base_version_id": "330601a7-a4c3-4e92-beac-4d56d32a4b5d",
- "path": "string",
- "new_path": "string",
- "blob_hash": "string",
- "size": 0,
- "content_type": "string",
- "client_mtime": "2019-08-24T14:15:22Z"
}
]
}{- "head_seq": 0,
- "results": [
- {
- "op_index": 0,
- "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
- "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
- "seq": 0
}
]
}| vault_id required | string <uuid> |
| hashes required | Array of strings <= 1000 items [ items^[0-9a-f]{64}$ ] |
{- "hashes": [
- "string"
]
}{- "missing": [
- "string"
]
}The server checks the bytes against the hash and the plan's limits. Larger blobs use upload sessions.
| vault_id required | string <uuid> |
| hash required | string^[0-9a-f]{64}$ |
{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}| vault_id required | string <uuid> |
| hash required | string^[0-9a-f]{64}$ |
| Range | string <= 100 characters One range, |
{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}| vault_id required | string <uuid> |
| hash required | string^[0-9a-f]{64}$ |
| size required | integer <int64> >= 0 |
{- "hash": "string",
- "size": 0
}{- "upload_id": "string",
- "hash": "string",
- "size": 0,
- "received": 0
}Upload-Offset must equal the bytes received so far (code upload_offset_mismatch otherwise).
| vault_id required | string <uuid> |
| upload_id required | string^[0-9a-f]{32}$ |
| Upload-Offset required | integer <int64> >= 0 |
{- "upload_id": "string",
- "hash": "string",
- "size": 0,
- "received": 0
}Checks the bytes against the hash and stores the blob.
| vault_id required | string <uuid> |
| upload_id required | string^[0-9a-f]{32}$ |
{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Superseded versions are kept for the plan's history period (PLAN.md 1.2).
| vault_id required | string <uuid> |
| file_id required | string <uuid> |
| before | integer <int64> >= 1 Return versions with a lower seq (from |
| limit | integer <int32> [ 1 .. 200 ] Default: 50 Maximum items to return. |
{- "versions": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
- "seq": 0,
- "op": "put",
- "path": "string",
- "blob_hash": "string",
- "size": 0,
- "content_type": "string",
- "deleted": true,
- "author_id": "78424c75-5c41-4b25-9735-3c9f7d05c59e",
- "author_name": "string",
- "author_email": "string",
- "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
- "created_at": "2019-08-24T14:15:22Z"
}
], - "next_before": 0
}Download its content with GET /v1/vaults/{vault_id}/blobs/{blob_hash}.
| vault_id required | string <uuid> |
| file_id required | string <uuid> |
| version_id required | string <uuid> |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
- "seq": 0,
- "op": "put",
- "path": "string",
- "blob_hash": "string",
- "size": 0,
- "content_type": "string",
- "deleted": true,
- "author_id": "78424c75-5c41-4b25-9735-3c9f7d05c59e",
- "author_name": "string",
- "author_email": "string",
- "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
- "created_at": "2019-08-24T14:15:22Z"
}Commits a new version with the old content at the file's current path (a deleted file comes back).
| vault_id required | string <uuid> |
| file_id required | string <uuid> |
| version_id required | string <uuid> |
{- "head_seq": 0,
- "results": [
- {
- "op_index": 0,
- "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
- "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
- "seq": 0
}
]
}Read and change single notes by their text, for scripts and integrations. Each change is an ordinary commit that synced devices, history, and search see.
Live files in path order (all kinds; GET on a non-text file answers not_a_note).
folder limits the list to one folder and its subfolders. Needs vaults:read.
| vault_id required | string <uuid> |
| folder | string <= 1024 characters |
| cursor | string <= 512 characters Opaque cursor from a previous page's |
| limit | integer <int32> [ 1 .. 200 ] Default: 50 Maximum items to return. |
{- "items": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "path": "string",
- "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
- "size": 0,
- "updated_at": "2019-08-24T14:15:22Z",
- "content": "string"
}
], - "next_cursor": "string"
}Creates a text file (.md, .txt, …) of at most 5 MB. A live file at the same path
(compared without case) answers 409 path_taken. Needs vaults:write, sync, or
notes:create (with folders:create too when the note's folder does not exist yet).
| vault_id required | string <uuid> |
| path required | string [ 1 .. 1024 ] characters |
| content required | string |
{- "path": "string",
- "content": "string"
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "path": "string",
- "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
- "size": 0,
- "updated_at": "2019-08-24T14:15:22Z",
- "content": "string"
}| vault_id required | string <uuid> |
| path required | string [ 1 .. 1024 ] characters |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "path": "string",
- "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
- "size": 0,
- "updated_at": "2019-08-24T14:15:22Z",
- "content": "string"
}| vault_id required | string <uuid> |
| file_id required | string <uuid> |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "path": "string",
- "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
- "size": 0,
- "updated_at": "2019-08-24T14:15:22Z",
- "content": "string"
}With base_version_id, answers 409 version_mismatch if the note changed since that
version; without it, the last write wins. Needs vaults:write, sync, or notes:edit.
| vault_id required | string <uuid> |
| file_id required | string <uuid> |
| content required | string |
| base_version_id | string <uuid> |
{- "content": "string",
- "base_version_id": "330601a7-a4c3-4e92-beac-4d56d32a4b5d"
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "path": "string",
- "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
- "size": 0,
- "updated_at": "2019-08-24T14:15:22Z",
- "content": "string"
}Applies find/replace (the first match, or every match with all), then prepend
and append. Without base_version_id the edit is applied to the newest text, so
concurrent edits from synced devices are kept. A missing find answers 400
find_not_found. Needs vaults:write, sync, or notes:edit.
| vault_id required | string <uuid> |
| file_id required | string <uuid> |
| find | string non-empty |
| replace | string |
| all | boolean Default: false |
| prepend | string |
| append | string |
| base_version_id | string <uuid> |
{- "find": "string",
- "replace": "string",
- "all": false,
- "prepend": "string",
- "append": "string",
- "base_version_id": "330601a7-a4c3-4e92-beac-4d56d32a4b5d"
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "path": "string",
- "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
- "size": 0,
- "updated_at": "2019-08-24T14:15:22Z",
- "content": "string"
}The note stays in version history and can be restored from there. Needs
vaults:write, sync, or notes:edit.
| vault_id required | string <uuid> |
| file_id required | string <uuid> |
| base_version_id | string <uuid> |
{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Links to the note are not rewritten. A taken path answers 409 path_taken. Needs
vaults:write, sync, or notes:edit (with folders:create too when the folder it
moves into does not exist yet).
| vault_id required | string <uuid> |
| file_id required | string <uuid> |
| path required | string [ 1 .. 1024 ] characters |
| base_version_id | string <uuid> |
{- "path": "string",
- "base_version_id": "330601a7-a4c3-4e92-beac-4d56d32a4b5d"
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "path": "string",
- "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
- "size": 0,
- "updated_at": "2019-08-24T14:15:22Z",
- "content": "string"
}Create, rename, move, and delete folders. A folder is a path prefix, there while it holds a file; moving or deleting one changes all its files in one commit.
A folder is there while it holds a file, so a new one starts with an empty
Untitled.md, as in the apps. A folder that already has files answers 409
folder_exists. Needs vaults:write, sync, or folders:create.
| vault_id required | string <uuid> |
| path required | string [ 1 .. 1024 ] characters |
{- "path": "string"
}{- "path": "string",
- "note": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "path": "string",
- "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
- "size": 0,
- "updated_at": "2019-08-24T14:15:22Z",
- "content": "string"
}
}Deletes every file in the folder and its subfolders in one commit (at most 500; a
larger folder answers 400 folder_too_large). Each file stays in version history and
can be restored. Needs vaults:write, sync, or folders:edit.
| vault_id required | string <uuid> |
| path required | string [ 1 .. 1024 ] characters |
{- "path": "string",
- "files": 0
}Moves every file in the folder and its subfolders to to (the folder's full new
path) in one commit, so it happens entirely or not at all (at most 500 files). A file
already at a new path answers 409 path_taken. Links are not rewritten. Needs
vaults:write, sync, or folders:edit.
| vault_id required | string <uuid> |
| from required | string [ 1 .. 1024 ] characters |
| to required | string [ 1 .. 1024 ] characters The folder's full new path. |
{- "from": "string",
- "to": "string"
}{- "path": "string",
- "files": 0
}The vault's note templates (Markdown notes in its templates folder), and notes made from them.
Fills the template's {{title}} (the new note's title), {{date}} (YYYY-MM-DD), and
{{time}} (HH:mm) in timezone, as the apps do. Without path, the note is named after
the template in folder (the top level when left out), numbered when the name is taken.
An unknown template answers 404 template_not_found. Needs vaults:write, sync, or
notes:create (with folders:create too when the folder does not exist yet).
| vault_id required | string <uuid> |
| template required | string [ 1 .. 1024 ] characters The template's path, or its name in the templates folder ("Meeting"). |
| path | string <= 1024 characters The new note's path. Left out, the note is named after the template. |
| folder | string <= 1024 characters Where the note goes when |
| timezone | string <= 64 characters An IANA time zone for |
{- "template": "string",
- "path": "string",
- "folder": "string",
- "timezone": "string"
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "path": "string",
- "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
- "size": 0,
- "updated_at": "2019-08-24T14:15:22Z",
- "content": "string"
}The Markdown notes in the vault's templates folder (templatesFolder in
.granite/settings.json, Templates by default), without their text. Needs
vaults:read or any write scope.
| vault_id required | string <uuid> |
{- "folder": "string",
- "items": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "path": "string",
- "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
- "size": 0,
- "updated_at": "2019-08-24T14:15:22Z",
- "content": "string"
}
]
}Saves content as name.md in the templates folder. A taken name answers 409
path_taken. Needs vaults:write, sync, or templates:edit.
| vault_id required | string <uuid> |
| name required | string [ 1 .. 255 ] characters The template's name; ".md" is added. |
| content required | string |
{- "name": "string",
- "content": "string"
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "path": "string",
- "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
- "size": 0,
- "updated_at": "2019-08-24T14:15:22Z",
- "content": "string"
}As updating a note, for a file in the templates folder (others answer 404
template_not_found). Needs vaults:write, sync, or templates:edit.
| vault_id required | string <uuid> |
| file_id required | string <uuid> |
| content required | string |
| base_version_id | string <uuid> |
{- "content": "string",
- "base_version_id": "330601a7-a4c3-4e92-beac-4d56d32a4b5d"
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "path": "string",
- "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c",
- "size": 0,
- "updated_at": "2019-08-24T14:15:22Z",
- "content": "string"
}It stays in version history and can be restored. Needs vaults:write, sync, or
templates:edit.
| vault_id required | string <uuid> |
| file_id required | string <uuid> |
| base_version_id | string <uuid> |
{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Signed HTTP callbacks for vault events, and integrations built on them. Granite posts a
JSON WebhookEvent to your URL within seconds of each change.
Integrations connect a service to one vault so it can act on notes and folders. Chat
apps (slack, teams, mattermost, discord, telegram, rocket_chat, zulip)
take commands; automation tools (n8n, pipedream, zapier, make, ifttt,
activepieces, power_automate, webhook) and shortcuts take actions. Automation
tools can, optionally, start a workflow when a note is added, moved, or deleted
(note.created, note.moved, note.deleted): the signed WebhookEvent JSON described
below, posted to their url. Edits never start an integration's workflow; only a custom
webhook may subscribe to note.updated or *. Chat apps get no events. Which kinds a plan may use, and
how many per vault, is in GET /v1/me/entitlements (integrations,
integrations_per_vault); custom webhooks need a paid plan. An integration's
addresses and secrets are stored encrypted and never shown again.
Commands and actions go to the integration's inbound_url
(POST /v1/integrations/{id}/inbound) and run as the person who installed it, in its
vault only, limited to its actions. Chat commands: new <title or path> (a line break
or | starts the text), append <note> | <text>, daily <text>, search <words>,
list <folder>, read <note>, replace <note> | <text>, move <note or folder> | <new name or path>, delete <note> (a folder with a trailing /), and plain text,
which is captured to <folder>/Inbox.md. Each service proves itself its own way:
Slack's signing secret, Discord's Ed25519 key, Telegram's secret token (and only the
connected chat), Teams' HMAC, or the token of a Mattermost, Rocket.Chat, or Zulip
webhook. Automation tools send JSON with the action_key as Authorization: Bearer …
(or ?key=): {"action": "create", "title": "…", "content": "…", "folder": "…"}, and
likewise append, daily, capture, search (query), list (folder), read,
update, move (path or folder, and to), delete (path or folder). A change
made this way is not sent back to the same integration as a trigger. Until its secrets
are saved (ready), an integration answers nothing.
AI meeting notetakers send each finished meeting to inbound_url with their own
webhook, and Granite saves it as a note in the integration's folder (default
Meetings): summary, action items as tasks, attendees, a link to the recording, and the
transcript in a folded callout; YAML frontmatter has type: meeting, source, date,
attendees, and meeting_id. The same meeting sent again replaces its own note.
Requests are checked with the service's signing secret (signing_secret): Read.ai's
X-Read-Signature, Fathom's and Granola's Standard Webhooks signature (whsec_…),
Fireflies' X-Hub-Signature, Circleback's X-Signature, Avoma's X-Avoma-Signature,
or MeetGeek's X-MG-Signature. tl;dv sends the action_key as a header, Otter as
?key=. Fireflies, Granola, and MeetGeek send only the meeting's ID; Granite fetches it
with the API key saved as inbound_token.
Answer with any 2xx status within 10 seconds; other answers and timeouts are retried after 1 min, 5 min, 30 min,
2 h, 6 h, and 24 h, then the delivery is marked failed (410 Gone stops retries at
once). Every attempt is in the delivery log and any delivery can be replayed. Delivery
is at least once: skip event ids you have already handled.
Events: note.created, note.updated, note.moved, note.deleted; vault.shared
and member.added/member.removed/member.role_changed start with sharing.
Subscribe with exact names, note.*, member.*, or *.
Headers: Granite-Event, Granite-Delivery, Granite-Webhook, and
Granite-Signature: t=<unix seconds>,v1=<signature>, where the signature is the hex
HMAC-SHA256 of <t>.<raw body> keyed with the webhook secret (whsec_...). Check it
against the raw body before parsing, and reject timestamps more than 5 minutes old.
Node.js:
import { createHmac, timingSafeEqual } from "node:crypto";
function verify(secret, header, rawBody) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;
const want = createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex");
return timingSafeEqual(Buffer.from(want), Buffer.from(parts.v1 ?? ""));
}
Python:
import hashlib, hmac, time
def verify(secret: str, header: str, raw_body: bytes) -> bool:
parts = dict(p.split("=", 1) for p in header.split(","))
if abs(time.time() - int(parts["t"])) > 300:
return False
want = hmac.new(secret.encode(), parts["t"].encode() + b"." + raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(want, parts.get("v1", ""))
Go:
func verify(secret, header string, body []byte) bool {
var t, sig string
for _, p := range strings.Split(header, ",") {
k, v, _ := strings.Cut(p, "=")
if k == "t" { t = v } else if k == "v1" { sig = v }
}
ts, err := strconv.ParseInt(t, 10, 64)
if err != nil || math.Abs(time.Since(time.Unix(ts, 0)).Seconds()) > 300 {
return false
}
m := hmac.New(sha256.New, []byte(secret))
m.Write([]byte(t + "."))
m.Write(body)
return hmac.Equal([]byte(hex.EncodeToString(m.Sum(nil))), []byte(sig))
}
Needs administrator access to the vault.
| vault_id required | string <uuid> |
{- "items": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "vault_id": "432b199b-1f71-42bf-ba0b-33d512afa9de",
- "kind": "slack",
- "url": "string",
- "description": "string",
- "events": [
- "*"
], - "actions": [
- "capture"
], - "folder": "string",
- "inbound_url": "string",
- "ready": true,
- "last_inbound_at": "2019-08-24T14:15:22Z",
- "granite_bot": true,
- "chats": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "created_at": "2019-08-24T14:15:22Z"
}
], - "active": true,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}
]
}The kind must be in the plan (403 plan_limit_integration, or plan_limit_webhooks
for custom webhooks), and the vault under the plan's integrations_per_vault (403
too_many_webhooks). Events from now on are delivered. The secret is returned only
here and when rotated.
| vault_id required | string <uuid> |
| kind | string (IntegrationKind) Enum: "slack" "teams" "mattermost" "discord" "telegram" "rocket_chat" "zulip" "shortcuts" "n8n" "pipedream" "zapier" "make" "ifttt" "activepieces" "power_automate" "webhook" "read_ai" "fathom" "fireflies" "tldv" "otter" "granola" "circleback" "avoma" "meetgeek" "google_chat" "webex" "ntfy" The connected service. |
| url | string <= 2000 characters Automation tools: the https URL that starts the workflow (a catch hook), for triggers. Chat apps need none. |
| bot_token | string <= 100 characters
|
| chat_id | string <= 40 characters
|
| actions | Array of strings (IntegrationAction) Items Enum: "capture" "create" "append" "daily" "search" "list" "read" "update" "move" "delete" "meeting" |
| folder | string <= 200 characters |
| signing_secret | string <= 200 characters
|
| public_key | string <= 200 characters
|
| application_id | string <= 40 characters
|
| inbound_token | string <= 200 characters
|
| description | string <= 200 characters |
| events required | Array of strings (WebhookEventType) Items Enum: "*" "note.*" "member.*" "note.created" "note.updated" "note.moved" "note.deleted" "vault.shared" "member.added" "member.removed" "member.role_changed" |
{- "kind": "slack",
- "url": "string",
- "bot_token": "string",
- "chat_id": "string",
- "actions": [
- "capture"
], - "folder": "string",
- "signing_secret": "string",
- "public_key": "string",
- "application_id": "string",
- "inbound_token": "string",
- "description": "string",
- "events": [
- "*"
]
}{- "webhook": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "vault_id": "432b199b-1f71-42bf-ba0b-33d512afa9de",
- "kind": "slack",
- "url": "string",
- "description": "string",
- "events": [
- "*"
], - "actions": [
- "capture"
], - "folder": "string",
- "inbound_url": "string",
- "ready": true,
- "last_inbound_at": "2019-08-24T14:15:22Z",
- "granite_bot": true,
- "chats": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "created_at": "2019-08-24T14:15:22Z"
}
], - "active": true,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}, - "secret": "string",
- "action_key": "string"
}| vault_id required | string <uuid> |
| webhook_id required | string <uuid> |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "vault_id": "432b199b-1f71-42bf-ba0b-33d512afa9de",
- "kind": "slack",
- "url": "string",
- "description": "string",
- "events": [
- "*"
], - "actions": [
- "capture"
], - "folder": "string",
- "inbound_url": "string",
- "ready": true,
- "last_inbound_at": "2019-08-24T14:15:22Z",
- "granite_bot": true,
- "chats": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "created_at": "2019-08-24T14:15:22Z"
}
], - "active": true,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}Omitted fields keep their value. rotate_secret returns a new secret once.
| vault_id required | string <uuid> |
| webhook_id required | string <uuid> |
| url | string <= 2000 characters |
| bot_token | string <= 100 characters |
| chat_id | string <= 40 characters |
| actions | Array of strings (IntegrationAction) Items Enum: "capture" "create" "append" "daily" "search" "list" "read" "update" "move" "delete" "meeting" |
| folder | string <= 200 characters |
| signing_secret | string <= 200 characters
|
| public_key | string <= 200 characters
|
| application_id | string <= 40 characters
|
| inbound_token | string <= 200 characters
|
| rotate_action_key | boolean |
| description | string <= 200 characters |
| events | Array of strings (WebhookEventType) Items Enum: "*" "note.*" "member.*" "note.created" "note.updated" "note.moved" "note.deleted" "vault.shared" "member.added" "member.removed" "member.role_changed" |
| active | boolean |
| rotate_secret | boolean |
{- "url": "string",
- "bot_token": "string",
- "chat_id": "string",
- "actions": [
- "capture"
], - "folder": "string",
- "signing_secret": "string",
- "public_key": "string",
- "application_id": "string",
- "inbound_token": "string",
- "rotate_action_key": true,
- "description": "string",
- "events": [
- "*"
], - "active": true,
- "rotate_secret": true
}{- "webhook": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "vault_id": "432b199b-1f71-42bf-ba0b-33d512afa9de",
- "kind": "slack",
- "url": "string",
- "description": "string",
- "events": [
- "*"
], - "actions": [
- "capture"
], - "folder": "string",
- "inbound_url": "string",
- "ready": true,
- "last_inbound_at": "2019-08-24T14:15:22Z",
- "granite_bot": true,
- "chats": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "created_at": "2019-08-24T14:15:22Z"
}
], - "active": true,
- "created_at": "2019-08-24T14:15:22Z",
- "updated_at": "2019-08-24T14:15:22Z"
}, - "secret": "string",
- "action_key": "string"
}Its pending deliveries and delivery log are deleted too.
| vault_id required | string <uuid> |
| webhook_id required | string <uuid> |
{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}For integrations on Granite's own bot (granite_bot): a one-time code, valid for 30
minutes, and the link that carries it (Telegram's start link, Slack's or Discord's
install page). The chat it is used in, or where link CODE is typed, is connected.
| vault_id required | string <uuid> |
| webhook_id required | string <uuid> |
{- "code": "string",
- "url": "string",
- "group_url": "string",
- "expires_at": "2019-08-24T14:15:22Z"
}Commands from the chat no longer reach Granite.
| vault_id required | string <uuid> |
| webhook_id required | string <uuid> |
| chat_id required | string <uuid> |
{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Queues a ping event, sent right away, so you can check the connection.
| vault_id required | string <uuid> |
| webhook_id required | string <uuid> |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "event_id": "a7a26ff2-e851-45b6-9634-d595f45458b7",
- "event_type": "string",
- "state": "pending",
- "attempts": 0,
- "next_attempt_at": "2019-08-24T14:15:22Z",
- "last_status": 0,
- "last_error": "string",
- "replay_of": "eb051ed0-925f-449a-a6c5-0c118d499f91",
- "created_at": "2019-08-24T14:15:22Z",
- "delivered_at": "2019-08-24T14:15:22Z",
- "payload": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "type": "string",
- "created_at": "2019-08-24T14:15:22Z",
- "vault_id": "432b199b-1f71-42bf-ba0b-33d512afa9de",
- "data": { }
}
}Deliveries, newest first, with the outcome of their latest attempt.
| vault_id required | string <uuid> |
| webhook_id required | string <uuid> |
| cursor | string <= 512 characters Opaque cursor from a previous page's |
| limit | integer <int32> [ 1 .. 200 ] Default: 50 Maximum items to return. |
{- "items": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "event_id": "a7a26ff2-e851-45b6-9634-d595f45458b7",
- "event_type": "string",
- "state": "pending",
- "attempts": 0,
- "next_attempt_at": "2019-08-24T14:15:22Z",
- "last_status": 0,
- "last_error": "string",
- "replay_of": "eb051ed0-925f-449a-a6c5-0c118d499f91",
- "created_at": "2019-08-24T14:15:22Z",
- "delivered_at": "2019-08-24T14:15:22Z",
- "payload": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "type": "string",
- "created_at": "2019-08-24T14:15:22Z",
- "vault_id": "432b199b-1f71-42bf-ba0b-33d512afa9de",
- "data": { }
}
}
], - "next_cursor": "string"
}Creates a new delivery of the same event (same event id), sent right away.
| vault_id required | string <uuid> |
| webhook_id required | string <uuid> |
| delivery_id required | string <uuid> |
{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "event_id": "a7a26ff2-e851-45b6-9634-d595f45458b7",
- "event_type": "string",
- "state": "pending",
- "attempts": 0,
- "next_attempt_at": "2019-08-24T14:15:22Z",
- "last_status": 0,
- "last_error": "string",
- "replay_of": "eb051ed0-925f-449a-a6c5-0c118d499f91",
- "created_at": "2019-08-24T14:15:22Z",
- "delivered_at": "2019-08-24T14:15:22Z",
- "payload": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "type": "string",
- "created_at": "2019-08-24T14:15:22Z",
- "vault_id": "432b199b-1f71-42bf-ba0b-33d512afa9de",
- "data": { }
}
}The consent page and connected apps of Granite's OAuth 2.1 server. The protocol endpoints
themselves (/.well-known/oauth-authorization-server, /oauth/register,
/oauth/authorize, /oauth/token, /oauth/revoke) follow the OAuth RFCs and are not
part of this API.
For the consent page: validates the request an app sent to /oauth/authorize and
describes the app. When the request is invalid but its redirect URI is the app's,
error_redirect is where to send the browser.
| client_id required | string <= 200 characters |
| redirect_uri | string <= 2000 characters |
| response_type | string <= 50 characters |
| scope | string <= 500 characters |
| state | string <= 2000 characters |
| code_challenge | string <= 200 characters |
| code_challenge_method | string <= 20 characters |
| resource | string <= 2000 characters |
{- "client_id": "string",
- "client_name": "string",
- "client_uri": "string",
- "logo_uri": "string",
- "redirect_host": "string",
- "scopes": [
- "vaults:read"
], - "error_redirect": "string"
}Records the decision. Allowing creates (or updates) the app's grant with the chosen
permissions and vaults (empty vault_ids means all vaults). The browser goes to
redirect_to either way.
required | object (OAuthAuthorizeRequest) |
| approve required | boolean |
| scopes | Array of strings (OAuthScope) Items Enum: "vaults:read" "vaults:write" "kb:query" |
| vault_ids | Array of strings <uuid> <= 100 items [ items <uuid > ] |
{- "request": {
- "client_id": "string",
- "redirect_uri": "string",
- "response_type": "string",
- "scope": "string",
- "state": "string",
- "code_challenge": "string",
- "code_challenge_method": "string",
- "resource": "string"
}, - "approve": true,
- "scopes": [
- "vaults:read"
], - "vault_ids": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}{- "redirect_to": "string"
}{- "items": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "client_id": "string",
- "client_name": "string",
- "client_uri": "string",
- "scopes": [
- "vaults:read"
], - "vault_ids": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "created_at": "2019-08-24T14:15:22Z",
- "last_used_at": "2019-08-24T14:15:22Z"
}
]
}Its access ends at once; it has to ask again.
| grant_id required | string <uuid> |
{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Company workspaces (Business plan): members with roles (owner, admin, member, guest), invitations by email or link, and verified email domains that let colleagues join. Anyone who is not a member gets 404 for everything about a workspace.
Suggestions while typing whom to share with: active people (members and above) of the
workspaces where the caller is a member or above, matching q at the start of their
name, a word of it, or their email. Never the caller.
| q required | string [ 1 .. 100 ] characters |
{- "items": [
- {
- "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
- "email": "string",
- "name": "string",
- "avatar_url": "string"
}
]
}{- "items": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "slug": "string",
- "role": "owner",
- "domain_capture": true,
- "policy_block": "string",
- "created_at": "2019-08-24T14:15:22Z"
}
]
}You become its owner. It starts a 30-day Business trial, no card required; a person
without a plan that includes workspaces has one unpaid trial at a time (403
workspace_trial_in_use).
| name required | string [ 1 .. 100 ] characters |
| slug | string^[a-z0-9][a-z0-9-]{1,47}$ |
{- "name": "string",
- "slug": "string"
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "slug": "string",
- "role": "owner",
- "domain_capture": true,
- "policy_block": "string",
- "created_at": "2019-08-24T14:15:22Z"
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "slug": "string",
- "role": "owner",
- "domain_capture": true,
- "policy_block": "string",
- "created_at": "2019-08-24T14:15:22Z"
}Admins.
| workspace_id required | string <uuid> |
| name | string [ 1 .. 100 ] characters |
| domain_capture | boolean Deprecated Only false is accepted; workspaces are joined by invitation only. |
{- "name": "string",
- "domain_capture": true
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "slug": "string",
- "role": "owner",
- "domain_capture": true,
- "policy_block": "string",
- "created_at": "2019-08-24T14:15:22Z"
}The owner. Its vaults and keys are destroyed after the recovery window.
| workspace_id required | string <uuid> |
{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Members and above (the directory). Owners and admins also see each person's two-step verification, last sign-in, and storage.
| workspace_id required | string <uuid> |
{- "items": [
- {
- "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
- "email": "string",
- "name": "string",
- "role": "owner",
- "status": "active",
- "joined_at": "2019-08-24T14:15:22Z",
- "avatar_url": "string",
- "two_factor": true,
- "last_sign_in_at": "2019-08-24T14:15:22Z",
- "storage_bytes": 0
}
]
}Owners and admins (only the owner for admins), before deleting the person's account: a zip with each of their personal vaults as a folder of plain files. Not for the owner or guests.
| workspace_id required | string <uuid> |
| user_id required | string <uuid> |
{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Company accounts belong to the organization: the owner and admins (only the owner for
admins) delete them; the owner's and guests' accounts are refused (guest_account).
Needs a recent password check (POST /v1/auth/step-up). With transfer_to, the
person's personal vaults (folders, notes, and history) move to that member first;
otherwise they are purged (download them first with the export). The account is signed
out everywhere at once.
| workspace_id required | string <uuid> |
| user_id required | string <uuid> |
| transfer_to | string <uuid> Another member above Guest who receives the personal vaults. |
{- "transfer_to": "e54cab72-cb73-43f0-9b9f-9dd0d9bd5cd7"
}{- "moved": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string"
}
]
}Admins manage members and guests; only the owner manages admins.
| workspace_id required | string <uuid> |
| user_id required | string <uuid> |
| role required | string Enum: "admin" "member" "guest" |
{- "role": "admin"
}{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Admins (only the owner removes admins). Removing yourself is leaving.
| workspace_id required | string <uuid> |
| user_id required | string <uuid> |
{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}The owner; they become an admin.
| workspace_id required | string <uuid> |
| user_id required | string <uuid> |
{- "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
}{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}The owner must transfer ownership first.
| workspace_id required | string <uuid> |
{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Workspaces are joined by invitation only; always 404, as for a workspace you are not in. Kept for older apps.
| workspace_id required | string <uuid> |
{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Admins.
| workspace_id required | string <uuid> |
{- "items": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "email": "string",
- "role": "admin",
- "expires_at": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z",
- "link": "string"
}
]
}Admins. With email, sends an invitation for that address (single use, 7 days); without, returns a link anyone signed in can use until it expires (30 days) or is revoked. Only the owner invites admins.
| workspace_id required | string <uuid> |
string <= 254 characters | |
| role required | string Enum: "admin" "member" "guest" |
{- "email": "string",
- "role": "admin"
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "email": "string",
- "role": "admin",
- "expires_at": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z",
- "link": "string"
}Admins.
| workspace_id required | string <uuid> |
| invitation_id required | string <uuid> |
{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Admins. Add the returned TXT record to the domain's DNS, then verify.
| workspace_id required | string <uuid> |
| domain required | string <= 253 characters |
{- "domain": "string"
}{- "domain": "string",
- "txt_record": "string",
- "verified_at": "2019-08-24T14:15:22Z"
}Admins.
| workspace_id required | string <uuid> |
| domain required | string <= 253 characters |
{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Admins. Answers 409 domain_not_verified until the TXT record is visible.
| workspace_id required | string <uuid> |
| domain required | string <= 253 characters |
{- "domain": "string",
- "txt_record": "string",
- "verified_at": "2019-08-24T14:15:22Z"
}Workspaces are joined by invitation only, so this list is always empty. Kept for older apps.
{- "items": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string"
}
]
}Does not need sign-in. The token is sent in the body so it stays out of logs.
| token required | string <= 200 characters |
{- "token": "string"
}{- "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
- "workspace_name": "string",
- "role": "string",
- "email": "string"
}Email invitations work only for the invited, verified address.
| token required | string <= 200 characters |
{- "token": "string"
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "slug": "string",
- "role": "owner",
- "domain_capture": true,
- "policy_block": "string",
- "created_at": "2019-08-24T14:15:22Z"
}Admins.
| workspace_id required | string <uuid> |
| name required | string [ 1 .. 100 ] characters |
{- "name": "string"
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "members": 0
}Admins.
| workspace_id required | string <uuid> |
| group_id required | string <uuid> |
| name required | string [ 1 .. 100 ] characters |
{- "name": "string"
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "members": 0
}Admins. Its grants stop applying.
| workspace_id required | string <uuid> |
| group_id required | string <uuid> |
{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Members and above.
| workspace_id required | string <uuid> |
| group_id required | string <uuid> |
{- "items": [
- {
- "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
- "email": "string",
- "name": "string"
}
]
}Admins. Takes effect on the member's next request.
| workspace_id required | string <uuid> |
| group_id required | string <uuid> |
| user_id required | string <uuid> |
{- "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
}{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Admins.
| workspace_id required | string <uuid> |
| group_id required | string <uuid> |
| user_id required | string <uuid> |
{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Admins. Newest first. Filters combine.
| workspace_id required | string <uuid> |
| cursor | string <= 512 characters Opaque cursor from a previous page's |
| limit | integer <int32> [ 1 .. 200 ] Default: 50 Maximum items to return. |
| action | string <= 100 characters Actions starting with this, such as member. or vault.shared |
| actor | string <uuid> |
| since | string <date-time> |
| until | string <date-time> |
{- "items": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "at": "2019-08-24T14:15:22Z",
- "actor_id": "04f37679-bfbf-4906-b749-01756515cecf",
- "actor_email": "string",
- "via": "string",
- "action": "string",
- "target_type": "string",
- "target_id": "d3bcdc92-4191-401b-ad0c-42056c6efab9",
- "ip": "string",
- "user_agent": "string",
- "metadata": { }
}
], - "next_cursor": "string"
}Admins. CSV, or JSON with one event per line. Up to 100,000 events, newest first.
| workspace_id required | string <uuid> |
| format required | string Enum: "csv" "json" |
| action | string <= 100 characters |
| since | string <date-time> |
| until | string <date-time> |
Admins. 404 when SSO is not set up.
| workspace_id required | string <uuid> |
{- "protocol": "oidc",
- "issuer": "string",
- "client_id": "string",
- "saml": {
- "entity_id": "string",
- "acs_url": "string",
- "metadata_url": "string"
}, - "jit_role": "member",
- "enforced": true,
- "tested_at": "2019-08-24T14:15:22Z",
- "redirect_url": "string"
}Admins. For OpenID Connect, register redirect_url with the provider. For SAML, give
the identity provider's metadata (idp_metadata XML or idp_metadata_url) and register
Granite's service provider with it: saml.metadata_url serves Granite's metadata
(GET /v1/sso/saml/{workspace_id}/metadata); the provider posts responses to
saml.acs_url (POST /v1/sso/saml/{workspace_id}/acs). Responses must be signed (or
carry signed assertions); replayed assertions are refused; sign-in can start at Granite
or at the provider. Members at the workspace's verified domains, and people there with an
open email invitation (who join in its role), can then sign in with SSO; anyone else is
refused (sso_not_invited). enforced needs one successful SSO sign-in with the
current issuer and client first; then members at those domains (all but the owner)
must use SSO, and their other sessions cannot open the workspace's vaults.
| workspace_id required | string <uuid> |
| protocol | string Default: "oidc" Enum: "oidc" "saml" |
| issuer | string <= 500 characters OpenID Connect. |
| client_id | string <= 500 characters |
| idp_metadata | string <= 1048576 characters SAML identity provider metadata XML (leave out to keep the stored one). |
| idp_metadata_url | string <= 2000 characters Where to fetch the SAML identity provider metadata instead. |
| client_secret | string <= 2000 characters Required the first time; leave out to keep the stored secret. |
| jit_role | string Enum: "member" "guest" Not used (kept for older apps); see SSOConnection. |
| enforced required | boolean |
{- "protocol": "oidc",
- "issuer": "string",
- "client_id": "string",
- "idp_metadata": "string",
- "idp_metadata_url": "string",
- "client_secret": "string",
- "jit_role": "member",
- "enforced": true
}{- "protocol": "oidc",
- "issuer": "string",
- "client_id": "string",
- "saml": {
- "entity_id": "string",
- "acs_url": "string",
- "metadata_url": "string"
}, - "jit_role": "member",
- "enforced": true,
- "tested_at": "2019-08-24T14:15:22Z",
- "redirect_url": "string"
}| workspace_id required | string <uuid> |
{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Admins. SCIM 2.0 (RFC 7644) lives at base_url (/scim/v2): Users are the workspace's
members (emails at verified domains), Groups its groups. Deactivating or deleting a user
suspends or removes the membership and revokes the account's sessions, API tokens, and
OAuth grants at once. The owner cannot be deprovisioned through SCIM.
| workspace_id required | string <uuid> |
{- "enabled": true,
- "base_url": "string",
- "token_prefix": "string",
- "created_at": "2019-08-24T14:15:22Z",
- "last_used_at": "2019-08-24T14:15:22Z"
}| workspace_id required | string <uuid> |
{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Admins. The policy applies to the workspace's vaults at once: a refused request gets
403 with a policy_... error code (policy_two_factor_required,
policy_session_expired, policy_client_not_allowed, policy_mcp_off,
policy_mcp_read_only, policy_knowledge_base_off). Requiring two-step verification
needs it on for the admin first.
| workspace_id required | string <uuid> |
| require_two_factor required | boolean Members need two-step verification to use the workspace's vaults. |
| session_hours required | integer [ 0 .. 8760 ] How long after signing in a session may use the workspace's vaults (0 for no limit). |
| clients required | Array of strings non-empty Items Enum: "web" "desktop" "mobile" "api" Apps allowed to use the workspace's vaults ( |
| mcp required | string Enum: "on" "read_only" "off" What AI tools connected through MCP may do. |
| knowledge_base required | boolean |
| drive required | boolean Google Drive references (when available). |
{- "require_two_factor": true,
- "session_hours": 0,
- "clients": [
- "web"
], - "mcp": "on",
- "knowledge_base": true,
- "drive": true
}{- "require_two_factor": true,
- "session_hours": 0,
- "clients": [
- "web"
], - "mcp": "on",
- "knowledge_base": true,
- "drive": true
}Admins. New events are POSTed in batches ({"workspace_id", "events": [...]}) within a
minute, signed like webhooks (Granite-Signature). The secret is returned only here.
| workspace_id required | string <uuid> |
| url required | string <= 2000 characters |
{- "url": "string"
}{- "url": "string",
- "secret": "string",
- "last_error": "string"
}| workspace_id required | string <uuid> |
{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Comments on notes, kept outside the Markdown file. A thread's first comment is anchored to a quote of the text with a little context before and after; clients find the quote again after edits. Mentioned people who can read the note are notified.
Oldest first; replies have parent_id.
| vault_id required | string <uuid> |
| file_id required | string <uuid> |
{- "items": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "parent_id": "1c6ca187-e61f-4301-8dcb-0e9749e89eef",
- "author_id": "78424c75-5c41-4b25-9735-3c9f7d05c59e",
- "author_email": "string",
- "author_name": "string",
- "author_avatar_url": "string",
- "body": "string",
- "anchor": {
- "quote": "string",
- "prefix": "string",
- "suffix": "string",
- "line": 0
}, - "resolved_at": "2019-08-24T14:15:22Z",
- "edited_at": "2019-08-24T14:15:22Z",
- "deleted": true,
- "created_at": "2019-08-24T14:15:22Z"
}
]
}Needs comment access to the note. mentions lists people to notify (those who cannot read the note are skipped).
| vault_id required | string <uuid> |
| file_id required | string <uuid> |
| body required | string [ 1 .. 10000 ] characters |
object (CommentAnchor) | |
| parent_id | string <uuid> |
| mentions | Array of strings <uuid> <= 50 items [ items <uuid > ] |
{- "body": "string",
- "anchor": {
- "quote": "string",
- "prefix": "string",
- "suffix": "string",
- "line": 0
}, - "parent_id": "1c6ca187-e61f-4301-8dcb-0e9749e89eef",
- "mentions": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}{- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "parent_id": "1c6ca187-e61f-4301-8dcb-0e9749e89eef",
- "author_id": "78424c75-5c41-4b25-9735-3c9f7d05c59e",
- "author_email": "string",
- "author_name": "string",
- "author_avatar_url": "string",
- "body": "string",
- "anchor": {
- "quote": "string",
- "prefix": "string",
- "suffix": "string",
- "line": 0
}, - "resolved_at": "2019-08-24T14:15:22Z",
- "edited_at": "2019-08-24T14:15:22Z",
- "deleted": true,
- "created_at": "2019-08-24T14:15:22Z"
}Only the author edits body; anyone who may comment resolves a thread.
| vault_id required | string <uuid> |
| comment_id required | string <uuid> |
| body | string [ 1 .. 10000 ] characters |
| resolved | boolean |
{- "body": "string",
- "resolved": true
}{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}The author or a vault admin. Replies stay.
| vault_id required | string <uuid> |
| comment_id required | string <uuid> |
{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}| cursor | string <= 512 characters Opaque cursor from a previous page's |
| limit | integer <int32> [ 1 .. 200 ] Default: 50 Maximum items to return. |
{- "items": [
- {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "kind": "mention",
- "actor_id": "04f37679-bfbf-4906-b749-01756515cecf",
- "actor_email": "string",
- "actor_name": "string",
- "actor_avatar_url": "string",
- "vault_id": "432b199b-1f71-42bf-ba0b-33d512afa9de",
- "vault_name": "string",
- "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
- "path": "string",
- "folder": true,
- "comment_id": "24dbb54d-334d-4b2a-92ae-e15845e5d822",
- "group_id": "306db4e0-7449-4501-b76f-075576fe2d8f",
- "group_name": "string",
- "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
- "workspace_name": "string",
- "read_at": "2019-08-24T14:15:22Z",
- "created_at": "2019-08-24T14:15:22Z"
}
], - "unread": 0,
- "next_cursor": "string"
}The listed ones, or all when ids is empty.
| ids | Array of strings <uuid> <= 200 items [ items <uuid > ] |
{- "ids": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
]
}{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}Searches the notes of one vault the caller may read. Query syntax: words match by
prefix and all must match; "a phrase"; -word excludes; tag:x (also finds #x/y),
path:x, and file:x filter. Matching ignores case and accents. Notes are indexed a few
seconds after each commit; pending counts notes not indexed yet.
| vault_id required | string <uuid> |
| q required | string [ 1 .. 500 ] characters |
| limit | integer [ 1 .. 50 ] Default: 20 |
{- "results": [
- {
- "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
- "path": "string",
- "title": "string",
- "snippet": "string",
- "line": 0,
- "score": 0.1
}
], - "pending": 0
}Retrieval for AI tools (Pro and Business). Granite has no built-in assistant: tools search the knowledge base and get ranked passages with citations, then answer with their own model. Only vaults the caller may read are searched.
Vault admins. Applies at once: an excluded folder's passages are removed from the index in this request, and files that come back in are queued for indexing.
| vault_id required | string <uuid> |
| included required | boolean The vault is in the knowledge base (when the plan includes it). |
| excluded_folders required | Array of strings <= 100 items Folders (with everything inside) left out of the knowledge base. |
| exclude_drive required | boolean Leave Google Drive references out. |
{- "included": true,
- "excluded_folders": [
- "string"
], - "exclude_drive": true
}{- "included": true,
- "excluded_folders": [
- "string"
], - "exclude_drive": true
}Vault admins.
| vault_id required | string <uuid> |
{- "available": true,
- "indexed": true,
- "documents": 0,
- "chunks": 0,
- "pending": 0,
- "last_indexed_at": "2019-08-24T14:15:22Z",
- "failures": [
- {
- "path": "string",
- "error": "string"
}
]
}Ranks note and document passages (chunks split by headings, pages of PDFs) by full-text
relevance and, when semantic search is enabled, meaning, fused by reciprocal rank.
Searches every vault the caller may read, or only vault_ids. Needs a plan with the
knowledge base (403 plan_limit_knowledge_base); tokens need the kb:query scope.
60 searches a minute per caller (429 kb_rate_limited). Files are indexed within a
minute of a change; pending counts files waiting.
| query required | string [ 1 .. 2000 ] characters |
| vault_ids | Array of strings <uuid> <= 100 items [ items <uuid > ] |
| limit | integer [ 1 .. 50 ] Default: 10 |
{- "query": "string",
- "vault_ids": [
- "497f6eca-6276-4993-bfeb-53cbbbba6f08"
], - "limit": 10
}{- "passages": [
- {
- "chunk_id": "55e808e1-8ddc-49f1-92c9-6bbdcdff1c83",
- "vault_id": "432b199b-1f71-42bf-ba0b-33d512afa9de",
- "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
- "path": "string",
- "title": "string",
- "type": "string",
- "heading_path": [
- "string"
], - "start_line": 0,
- "end_line": 0,
- "page": 0,
- "text": "string",
- "score": 0.1
}
], - "pending": 0
}Makes the note readable by anyone with the link at /p/{slug} (rendered on the server
from the note's current version and sanitized). Calling it again changes the address or
password. Needs vault admin access; the plan limits how many notes are published
(plan_limit_published_notes).
| vault_id required | string <uuid> |
| file_id required | string <uuid> |
| slug | string^[a-z0-9][a-z0-9-]{2,63}$ The page address; omitted keeps the current one or picks a random one. |
| password | string <= 256 characters Omitted keeps the current password; "" removes it. |
{- "slug": "string",
- "password": "string"
}{- "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
- "path": "string",
- "slug": "string",
- "protected": true
}| vault_id required | string <uuid> |
| file_id required | string <uuid> |
{- "title": "string",
- "status": 0,
- "detail": "string",
- "instance": "string",
- "code": "string",
- "request_id": "string",
- "errors": [
- {
- "field": "string",
- "detail": "string"
}
]
}