Granite API (1.0.0)

Download OpenAPI specification:

License: LicenseRef-Proprietary

REST API for Granite clients, bots, and integrations.

Conventions (apply to every operation; see PLAN.md 3.2 and 3.6):

  • Base URL https://api.granite.md. All public operations live under /v1. After Phase 6 ships, /v1 changes are additive only.
  • Errors use RFC 9457 problem details (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.
  • Pagination is cursor based. List operations accept 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.
  • Idempotency: non-idempotent 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.
  • IDs are UUIDv7 strings. Timestamps are RFC 3339 in UTC.
  • Authentication: Authorization: Bearer <token> with a session access token, a personal API token (gr_pat_...), or an OAuth access token. Scopes are listed per operation.
  • Rate limits: each personal API token may make 600 requests a minute. Over the limit the API answers 429 with code token_rate_limited and a Retry-After header (seconds).

meta

Service information.

Service information

Returns the API and server versions. Does not require authentication.

Responses

Response samples

Content type
application/json
{
  • "api_version": "1.0.0",
  • "server_version": "2026.10.1"
}

Report an app error

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.

Request Body schema: application/json
required
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

Responses

Request samples

Content type
application/json
{
  • "kind": "crash",
  • "message": "string",
  • "stack": "string",
  • "screen": "string",
  • "platform": "web",
  • "app_version": "string",
  • "os_version": "string"
}

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

auth

Sign-up, login, sessions, and password reset.

Create an account

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.

Request Body schema: application/json
required
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 (link, the web) or a 6-digit code to type into the app (code, the mobile apps).

Responses

Request samples

Content type
application/json
{
  • "email": "[email protected]",
  • "password": "stringstri",
  • "name": "string",
  • "workspace_name": "string",
  • "confirm": "link"
}

Response samples

Content type
application/json
{
  • "status": "accepted"
}

Confirm a sign-up with the emailed code and sign in

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.

Request Body schema: application/json
required
email
required
string <email> <= 254 characters
code
required
string <= 20 characters

The 6 digits from the email.

required
object (DeviceInfo)

Responses

Request samples

Content type
application/json
{
  • "email": "[email protected]",
  • "code": "string",
  • "device": {
    }
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "Bearer",
  • "expires_in": 0,
  • "refresh_token": "string",
  • "refresh_expires_in": 0,
  • "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
  • "user": {
    }
}

Confirm an email address

Request Body schema: application/json
required
token
required
string <= 200 characters

Responses

Request samples

Content type
application/json
{
  • "token": "string"
}

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Send a new verification email

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.

Request Body schema: application/json
required
email
required
string <email> <= 254 characters
confirm
string (EmailConfirmMode)
Enum: "link" "code"

How the email proves the address: a link to open (link, the web) or a 6-digit code to type into the app (code, the mobile apps).

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "status": "accepted"
}

Sign in

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.

Request Body schema: application/json
required
email
required
string <email> <= 254 characters
password
required
string <= 256 characters
required
object (DeviceInfo)

Responses

Request samples

Content type
application/json
{
  • "email": "[email protected]",
  • "password": "string",
  • "device": {
    }
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "Bearer",
  • "expires_in": 0,
  • "refresh_token": "string",
  • "refresh_expires_in": 0,
  • "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
  • "user": {
    }
}

Start single sign-on

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.

query Parameters
client
string
Enum: "web" "mobile"

Who finishes the sign-in; mobile for the phone app.

Request Body schema: application/json
required
email
required
string <= 320 characters

Responses

Request samples

Content type
application/json
{
  • "email": "string"
}

Response samples

Content type
application/json
{
  • "authorize_url": "string"
}

Finish single sign-on

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.

Request Body schema: application/json
required
state
string <= 200 characters
code
string <= 4000 characters
handoff
string <= 200 characters
required
object (DeviceInfo)

Responses

Request samples

Content type
application/json
{
  • "state": "string",
  • "code": "string",
  • "handoff": "string",
  • "device": {
    }
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "Bearer",
  • "expires_in": 0,
  • "refresh_token": "string",
  • "refresh_expires_in": 0,
  • "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
  • "user": {
    }
}

Get new tokens

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.

Request Body schema: application/json
required
refresh_token
required
string <= 200 characters

Responses

Request samples

Content type
application/json
{
  • "refresh_token": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "Bearer",
  • "expires_in": 0,
  • "refresh_token": "string",
  • "refresh_expires_in": 0,
  • "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
  • "user": {
    }
}

Sign out this device

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Email a password reset link or code

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.

Request Body schema: application/json
required
email
required
string <email> <= 254 characters
confirm
string (EmailConfirmMode)
Enum: "link" "code"

How the email proves the address: a link to open (link, the web) or a 6-digit code to type into the app (code, the mobile apps).

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "status": "accepted"
}

Set a new password

Sets the password from a reset link and signs out every device.

Request Body schema: application/json
required
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").

Responses

Request samples

Content type
application/json
{
  • "token": "string",
  • "password": "stringstri"
}

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Check an emailed reset code

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.

Request Body schema: application/json
required
email
required
string <email> <= 254 characters
code
required
string <= 20 characters

The 6 digits from the email.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Set a new password with an emailed code and sign in

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.

Request Body schema: application/json
required
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)

Responses

Request samples

Content type
application/json
{
  • "email": "[email protected]",
  • "code": "string",
  • "password": "stringstri",
  • "device": {
    }
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "Bearer",
  • "expires_in": 0,
  • "refresh_token": "string",
  • "refresh_expires_in": 0,
  • "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
  • "user": {
    }
}

Finish signing in with a second factor

Send either code (from the authenticator app) or recovery_code. Each works once.

Request Body schema: application/json
required
mfa_token
required
string <= 2000 characters
code
string <= 10 characters
recovery_code
string <= 40 characters

Responses

Request samples

Content type
application/json
{
  • "mfa_token": "string",
  • "code": "string",
  • "recovery_code": "string"
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "Bearer",
  • "expires_in": 0,
  • "refresh_token": "string",
  • "refresh_expires_in": 0,
  • "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
  • "user": {
    }
}

Confirm the password for sensitive actions

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.

Authorizations:
bearerAuth
Request Body schema: application/json
required
password
required
string <= 256 characters
code
string <= 10 characters

Authenticator code, required when two-factor authentication is on.

Responses

Request samples

Content type
application/json
{
  • "password": "string",
  • "code": "string"
}

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Hand a sign-in to the desktop app

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.

Authorizations:
bearerAuth
Request Body schema: application/json
required
code_challenge
required
string = 43 characters

base64url(SHA-256(code_verifier)) without padding (RFC 7636 S256).

Responses

Request samples

Content type
application/json
{
  • "code_challenge": "stringstringstringstringstringstringstrings"
}

Response samples

Content type
application/json
{
  • "code": "string",
  • "expires_in": 0
}

Redeem a sign-in handed to the app

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.

Request Body schema: application/json
required
code
required
string <= 200 characters
code_verifier
required
string [ 43 .. 128 ] characters
required
object (DeviceInfo)

Responses

Request samples

Content type
application/json
{
  • "code": "string",
  • "code_verifier": "stringstringstringstringstringstringstrings",
  • "device": {
    }
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "Bearer",
  • "expires_in": 0,
  • "refresh_token": "string",
  • "refresh_expires_in": 0,
  • "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
  • "user": {
    }
}

Sign in with Google or Apple

Send the ID token from the provider's sign-in SDK. Before signing in, the client makes a random nonce, passes hex(SHA-256(nonce)) to the provider, and sends the raw nonce here. A first sign-in with a verified email links to the account with that email or creates one. Returns 202 when the account has two-factor authentication on.

path Parameters
provider
required
string
Enum: "google" "apple"
Request Body schema: application/json
required
id_token
required
string <= 8000 characters
nonce
required
string [ 16 .. 200 ] characters
name
string <= 200 characters

Apple gives the user's name to the app only on the first sign-in.

authorization_code
string <= 2000 characters

Apple only: the authorization code Apple returned with the ID token. The server exchanges it for a refresh token, kept encrypted, so that deleting the account can revoke Granite's access to the person's Apple ID (App Store Review Guideline 5.1.1(v)). A failed exchange does not stop the sign-in.

workspace_name
string [ 1 .. 100 ] characters

Signs up for a business account (with a company's Google Workspace account, say): when this sign-in creates the account, it also gets a workspace of this name, owned by it, on the 30-day Business trial. Ignored for an existing account.

required
object (DeviceInfo)

Responses

Request samples

Content type
application/json
{
  • "id_token": "string",
  • "nonce": "stringstringstri",
  • "name": "string",
  • "authorization_code": "string",
  • "workspace_name": "string",
  • "device": {
    }
}

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "token_type": "Bearer",
  • "expires_in": 0,
  • "refresh_token": "string",
  • "refresh_expires_in": 0,
  • "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
  • "user": {
    }
}

me

The signed-in user.

The signed-in user

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "[email protected]",
  • "name": "string",
  • "email_verified": true,
  • "two_factor_enabled": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "avatar_url": "string"
}

Change your profile

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string <= 200 characters

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "[email protected]",
  • "name": "string",
  • "email_verified": true,
  • "two_factor_enabled": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "avatar_url": "string"
}

Delete the account

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.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Download everything in the account

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.

Authorizations:
bearerAuth

Responses

Response samples

Content type
No sample

Upload a profile photo

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.

Authorizations:
bearerAuth
Request Body schema: application/octet-stream
required
string <binary>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "email": "[email protected]",
  • "name": "string",
  • "email_verified": true,
  • "two_factor_enabled": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "avatar_url": "string"
}

Remove the profile photo

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

A profile photo

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.

path Parameters
avatar_id
required
string^[A-Za-z0-9_-]{22}$

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Which notifications reach you by email and on your phones

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.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "email": {
    },
  • "push": {
    }
}

Save which notifications reach you

Replaces all of them at once. In-app notifications (the bell) always arrive.

Authorizations:
bearerAuth
Request Body schema: application/json
required
required
object (NotificationChannels)

One switch per kind. comment: replies in threads you wrote in. share: a vault, folder, or note shared with you. mention: you were mentioned in a comment. resolved: a comment thread on a note you created or edited was resolved.

required
object (NotificationChannels)

One switch per kind. comment: replies in threads you wrote in. share: a vault, folder, or note shared with you. mention: you were mentioned in a comment. resolved: a comment thread on a note you created or edited was resolved.

Responses

Request samples

Content type
application/json
{
  • "email": {
    },
  • "push": {
    }
}

Response samples

Content type
application/json
{
  • "email": {
    },
  • "push": {
    }
}

Your appearance preferences

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.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "theme": "system",
  • "editor_font": "sans",
  • "font_size": 15,
  • "readable_width": true,
  • "live_preview": true,
  • "line_numbers": true,
  • "updated_at": "2019-08-24T14:15:22Z"
}

Save your appearance preferences

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.

Authorizations:
bearerAuth
Request Body schema: application/json
required
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).

Responses

Request samples

Content type
application/json
{
  • "theme": "system",
  • "editor_font": "sans",
  • "font_size": 15,
  • "readable_width": true,
  • "live_preview": true,
  • "line_numbers": true
}

Response samples

Content type
application/json
{
  • "theme": "system",
  • "editor_font": "sans",
  • "font_size": 15,
  • "readable_width": true,
  • "live_preview": true,
  • "line_numbers": true,
  • "updated_at": "2019-08-24T14:15:22Z"
}

Change your password

Requires a recent step-up (POST /v1/auth/step-up). Signs out every other device.

Authorizations:
bearerAuth
Request Body schema: application/json
required
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").

Responses

Request samples

Content type
application/json
{
  • "password": "stringstri"
}

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Your signed-in devices

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.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Sign out every other device

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Rename a device

Authorizations:
bearerAuth
path Parameters
device_id
required
string <uuid>
Request Body schema: application/json
required
name
required
string [ 1 .. 100 ] characters

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "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
}

Sign a device out

Its sessions end; its access tokens stop working within 30 seconds.

Authorizations:
bearerAuth
path Parameters
device_id
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Your personal API tokens

Tokens that are not revoked. Token values are never shown again.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create a personal API token

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>.

Authorizations:
bearerAuth
Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "scopes": [
    ],
  • "expires_in_days": 1
}

Response samples

Content type
application/json
{
  • "token": {
    },
  • "value": "string"
}

Revoke a personal API token

The token stops working at once.

Authorizations:
bearerAuth
path Parameters
token_id
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Every plan and its limits

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.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Plan, limits, and usage

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).

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "plan": {
    },
  • "limits": {
    },
  • "usage": {
    }
}

Feature flags

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.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "flags": {
    }
}

Turn off two-factor authentication

Requires a recent step-up.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Start authenticator app setup

Returns a new secret to show as a QR code. Requires a recent step-up.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "secret": "string",
  • "otpauth_uri": "string"
}

Finish authenticator app setup

Turns two-factor authentication on and returns recovery codes, shown only once.

Authorizations:
bearerAuth
Request Body schema: application/json
required
code
required
string <= 10 characters

Responses

Request samples

Content type
application/json
{
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "recovery_codes": [
    ]
}

Replace recovery codes

Old codes stop working. Requires a recent step-up.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "recovery_codes": [
    ]
}

Receive push notifications on this device

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.

Authorizations:
bearerAuth
Request Body schema: application/json
required
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).

Responses

Request samples

Content type
application/json
{
  • "provider": "apns",
  • "token": "string",
  • "sandbox": false
}

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Stop push notifications on this device

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

shopify

Shopify stores connected with the Granite for Shopify app.

Shopify stores connected to you

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.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Disconnect a Shopify store

The store stops syncing; its vault and notes stay where they are.

Authorizations:
bearerAuth
path Parameters
shop_domain
required
string <= 255 characters

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

vaults

Vaults (folders of notes that sync).

List vaults

Authorizations:
bearerAuth
query Parameters
cursor
string <= 512 characters

Opaque cursor from a previous page's next_cursor.

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.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string"
}

Create a vault

Authorizations:
bearerAuth
Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9"
}

Response samples

Content type
application/json
{
  • "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"
}

Get a vault

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "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"
}

Rename a vault

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
Request Body schema: application/json
required
name
required
string [ 1 .. 100 ] characters

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "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"
}

Move a vault to the trash

The vault can be restored for 30 days (purge_after), then it is deleted permanently.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "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"
}

Download a vault as a zip of plain files

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).

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Restore a vault from the trash

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "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"
}

Who a shared vault is shared with

Vault admins.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Share a vault, a folder, or a note

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.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
Request Body schema: application/json
required
principal_type
required
string
Enum: "user" "group"
principal_id
required
string <uuid>
access
required
string
Enum: "read" "comment" "write" "admin"
folder
string <= 1024 characters

Responses

Request samples

Content type
application/json
{
  • "principal_type": "user",
  • "principal_id": "b0fe3bdd-8201-445a-aab3-a018692d6aca",
  • "access": "read",
  • "folder": "string"
}

Response samples

Content type
application/json
{
  • "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"
}

Stop sharing

Vault admins. Applies from the next request.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
grant_id
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Restricted and private folders

Workspace owners and admins see all of them (private folders by name only); others see those they can open.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Restrict a folder or note, or make a folder private

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.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
Request Body schema: application/json
required
path
required
string [ 1 .. 1024 ] characters
private
required
boolean

Responses

Request samples

Content type
application/json
{
  • "path": "string",
  • "private": true
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "folder": "string",
  • "private": true,
  • "private_to": "ba469d7a-c1d2-41fd-a49e-f96862913789",
  • "created_at": "2019-08-24T14:15:22Z"
}

Lift a restriction or a folder's privacy

A private folder's member, or workspace owners and admins. Applies from the next request.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
restriction_id
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Who can open a folder or note

Anyone who can read the path. Says whether it is private or restricted and what the caller may change.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
query Parameters
path
required
string [ 1 .. 1024 ] characters

Responses

Response samples

Content type
application/json
{
  • "path": "string",
  • "private": true,
  • "restricted": true,
  • "restricted_at": "string",
  • "restriction": {
    },
  • "can_manage": true,
  • "can_make_private": true,
  • "openers": [
    ]
}

drive

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.

Your Google Drive connection

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "available": true,
  • "connected": true,
  • "google_account": "string",
  • "state": "ok",
  • "connected_at": "2019-08-24T14:15:22Z"
}

Disconnect Google Drive

Revokes Granite's access at Google. References stay as links; their content can no longer be read.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Start connecting Google Drive

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.

Authorizations:
bearerAuth
query Parameters
client
string
Enum: "web" "mobile"

Who finishes the sign-in; mobile for the phone app.

Responses

Response samples

Content type
application/json

Finish connecting Google Drive

Authorizations:
bearerAuth
Request Body schema: application/json
required
state
required
string [ 1 .. 200 ] characters
code
required
string [ 1 .. 2000 ] characters

Responses

Request samples

Content type
application/json
{
  • "state": "string",
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "available": true,
  • "connected": true,
  • "google_account": "string",
  • "state": "ok",
  • "connected_at": "2019-08-24T14:15:22Z"
}

A session for Google's file picker

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.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "access_token": "string",
  • "expires_at": "2019-08-24T14:15:22Z",
  • "api_key": "string",
  • "app_id": "string"
}

The vault's Drive references

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Reference a Drive file you picked

Editors only. Uses your connection; afterwards everyone who can read the vault can read the file through it.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
Request Body schema: application/json
required
drive_file_id
required
string [ 1 .. 200 ] characters

Responses

Request samples

Content type
application/json
{
  • "drive_file_id": "string"
}

Response samples

Content type
application/json
{
  • "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"
}

Remove a reference

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
ref_id
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Read a referenced file's text

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.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
ref_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "ref": {
    },
  • "text": "string",
  • "format": "markdown",
  • "truncated": true
}

billing

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).

Plan, subscription, and storage use

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.

Authorizations:
bearerAuth
query Parameters
workspace_id
string <uuid>

A workspace you own; omit for your own billing.

Responses

Response samples

Content type
application/json
{
  • "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": {
    },
  • "company": {
    }
}

Buy Pro or Business

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.

Authorizations:
bearerAuth
Request Body schema: application/json
required
plan
required
string
Enum: "pro" "business"
workspace_id
string <uuid>
seats
integer <int64> [ 2 .. 10000 ]

Responses

Request samples

Content type
application/json
{
  • "plan": "pro",
  • "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
  • "seats": 2
}

Response samples

Content type
application/json

Manage payment method, invoices, and cancelation

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).

Authorizations:
bearerAuth
Request Body schema: application/json
required
workspace_id
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9"
}

Response samples

Content type
application/json

Record a Pro purchase made in the iPhone or iPad app

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.

Authorizations:
bearerAuth
Request Body schema: application/json
required
signed_transaction
required
string [ 1 .. 20000 ] characters

Responses

Request samples

Content type
application/json
{
  • "signed_transaction": "string"
}

Response samples

Content type
application/json
{
  • "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": {
    },
  • "company": {
    }
}

Record a Pro purchase made in the Android app

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.

Authorizations:
bearerAuth
Request Body schema: application/json
required
purchase_token
required
string [ 1 .. 4096 ] characters

Responses

Request samples

Content type
application/json
{
  • "purchase_token": "string"
}

Response samples

Content type
application/json
{
  • "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": {
    },
  • "company": {
    }
}

Latest invoices

Authorizations:
bearerAuth
query Parameters
workspace_id
string <uuid>

A workspace you own; omit for your own billing.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Saved cards

The cards saved with Stripe, the default first. None before the first purchase or card.

Authorizations:
bearerAuth
query Parameters
workspace_id
string <uuid>

A workspace you own; omit for your own billing.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Add a card

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.

Authorizations:
bearerAuth
Request Body schema: application/json
required
workspace_id
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9"
}

Response samples

Content type
application/json

Remove a card

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.

Authorizations:
bearerAuth
path Parameters
payment_method_id
required
string [ 1 .. 255 ] characters

Stripe's ID of the card (pm_...).

query Parameters
workspace_id
string <uuid>

A workspace you own; omit for your own billing.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Pay with this card

Makes the card the default for future invoices, including the current subscription's.

Authorizations:
bearerAuth
path Parameters
payment_method_id
required
string [ 1 .. 255 ] characters

Stripe's ID of the card (pm_...).

Request Body schema: application/json
required
workspace_id
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9"
}

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

sync

The sync protocol (PLAN.md Appendix B).

Snapshot of the vault's files

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).

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
query Parameters
at
integer <int64> >= 0
cursor
string <= 512 characters

Opaque cursor from a previous page's next_cursor.

limit
integer <int32> [ 1 .. 200 ]
Default: 50

Maximum items to return.

Responses

Response samples

Content type
application/json
{
  • "head_seq": 0,
  • "files": [
    ],
  • "next_cursor": "string"
}

Changes after a sequence number

Answers 410 with code cursor_expired when since is older than the kept log.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
query Parameters
since
required
integer <int64> >= 0
limit
integer [ 1 .. 1000 ]
Default: 500

Responses

Response samples

Content type
application/json
{
  • "changes": [
    ],
  • "head_seq": 0,
  • "has_more": true
}

Who created and last changed a note, and who can open it

Anyone who can read the note. created_by is absent once history no longer reaches the first version.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
file_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
  • "path": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "created_by": {
    },
  • "modified_at": "2019-08-24T14:15:22Z",
  • "modified_by": {
    },
  • "size": 0,
  • "versions": 0,
  • "access": {
    },
  • "shared_with": [
    ]
}

Apply a batch of changes atomically

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
header Parameters
Idempotency-Key
string [ 1 .. 255 ] characters ^[\x21-\x7E]+$

Makes a non-idempotent POST safe to retry. See the conventions above.

Request Body schema: application/json
required
device_id
string <uuid>
required
Array of objects (CommitOp) <= 1000 items

Responses

Request samples

Content type
application/json
{
  • "device_id": "3bafab7b-4400-4bcf-8e6e-09f954699940",
  • "ops": [
    ]
}

Response samples

Content type
application/json
{
  • "head_seq": 0,
  • "results": [
    ]
}

Which blobs still need uploading

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
Request Body schema: application/json
required
hashes
required
Array of strings <= 1000 items [ items^[0-9a-f]{64}$ ]

Responses

Request samples

Content type
application/json
{
  • "hashes": [
    ]
}

Response samples

Content type
application/json
{
  • "missing": [
    ]
}

Upload a blob (up to 8 MiB)

The server checks the bytes against the hash and the plan's limits. Larger blobs use upload sessions.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
hash
required
string^[0-9a-f]{64}$
Request Body schema: application/octet-stream
required
string <binary>

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Download a blob

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
hash
required
string^[0-9a-f]{64}$
header Parameters
Range
string <= 100 characters

One range, bytes=start-end or bytes=start-.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Start a resumable upload

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
Request Body schema: application/json
required
hash
required
string^[0-9a-f]{64}$
size
required
integer <int64> >= 0

Responses

Request samples

Content type
application/json
{
  • "hash": "string",
  • "size": 0
}

Response samples

Content type
application/json
{
  • "upload_id": "string",
  • "hash": "string",
  • "size": 0,
  • "received": 0
}

How much of an upload arrived

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
upload_id
required
string^[0-9a-f]{32}$

Responses

Response samples

Content type
application/json
{
  • "upload_id": "string",
  • "hash": "string",
  • "size": 0,
  • "received": 0
}

Send the next part (up to 16 MiB)

Upload-Offset must equal the bytes received so far (code upload_offset_mismatch otherwise).

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
upload_id
required
string^[0-9a-f]{32}$
header Parameters
Upload-Offset
required
integer <int64> >= 0
Request Body schema: application/octet-stream
required
string <binary>

Responses

Response samples

Content type
application/json
{
  • "upload_id": "string",
  • "hash": "string",
  • "size": 0,
  • "received": 0
}

Finish an upload

Checks the bytes against the hash and stores the blob.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
upload_id
required
string^[0-9a-f]{32}$

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

A file's version history, newest first

Superseded versions are kept for the plan's history period (PLAN.md 1.2).

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
file_id
required
string <uuid>
query Parameters
before
integer <int64> >= 1

Return versions with a lower seq (from next_before of the previous page).

limit
integer <int32> [ 1 .. 200 ]
Default: 50

Maximum items to return.

Responses

Response samples

Content type
application/json
{
  • "versions": [
    ],
  • "next_before": 0
}

One version

Download its content with GET /v1/vaults/{vault_id}/blobs/{blob_hash}.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
file_id
required
string <uuid>
version_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "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"
}

Make an old version current again

Commits a new version with the old content at the file's current path (a deleted file comes back).

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
file_id
required
string <uuid>
version_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "head_seq": 0,
  • "results": [
    ]
}

notes

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.

List notes

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.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
query Parameters
folder
string <= 1024 characters
cursor
string <= 512 characters

Opaque cursor from a previous page's next_cursor.

limit
integer <int32> [ 1 .. 200 ]
Default: 50

Maximum items to return.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string"
}

Create a note

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).

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
Request Body schema: application/json
required
path
required
string [ 1 .. 1024 ] characters
content
required
string

Responses

Request samples

Content type
application/json
{
  • "path": "string",
  • "content": "string"
}

Response samples

Content type
application/json
{
  • "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"
}

Read a note by its path

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
query Parameters
path
required
string [ 1 .. 1024 ] characters

Responses

Response samples

Content type
application/json
{
  • "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"
}

Read a note

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
file_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "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"
}

Replace a note's text

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.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
file_id
required
string <uuid>
Request Body schema: application/json
required
content
required
string
base_version_id
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "content": "string",
  • "base_version_id": "330601a7-a4c3-4e92-beac-4d56d32a4b5d"
}

Response samples

Content type
application/json
{
  • "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"
}

Edit part of a note

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.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
file_id
required
string <uuid>
Request Body schema: application/json
required
find
string non-empty
replace
string
all
boolean
Default: false
prepend
string
append
string
base_version_id
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "find": "string",
  • "replace": "string",
  • "all": false,
  • "prepend": "string",
  • "append": "string",
  • "base_version_id": "330601a7-a4c3-4e92-beac-4d56d32a4b5d"
}

Response samples

Content type
application/json
{
  • "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"
}

Delete a note

The note stays in version history and can be restored from there. Needs vaults:write, sync, or notes:edit.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
file_id
required
string <uuid>
query Parameters
base_version_id
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Rename or move a note

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).

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
file_id
required
string <uuid>
Request Body schema: application/json
required
path
required
string [ 1 .. 1024 ] characters
base_version_id
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "path": "string",
  • "base_version_id": "330601a7-a4c3-4e92-beac-4d56d32a4b5d"
}

Response samples

Content type
application/json
{
  • "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"
}

folders

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.

Create a folder

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.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
Request Body schema: application/json
required
path
required
string [ 1 .. 1024 ] characters

Responses

Request samples

Content type
application/json
{
  • "path": "string"
}

Response samples

Content type
application/json
{
  • "path": "string",
  • "note": {
    }
}

Delete a folder

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.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
query Parameters
path
required
string [ 1 .. 1024 ] characters

Responses

Response samples

Content type
application/json
{
  • "path": "string",
  • "files": 0
}

Rename or move a folder

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.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
Request Body schema: application/json
required
from
required
string [ 1 .. 1024 ] characters
to
required
string [ 1 .. 1024 ] characters

The folder's full new path.

Responses

Request samples

Content type
application/json
{
  • "from": "string",
  • "to": "string"
}

Response samples

Content type
application/json
{
  • "path": "string",
  • "files": 0
}

templates

The vault's note templates (Markdown notes in its templates folder), and notes made from them.

Create a note from a template

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).

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
Request Body schema: application/json
required
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 path is left out ("" or left out is the top level).

timezone
string <= 64 characters

An IANA time zone for {{date}} and {{time}} (UTC when left out).

Responses

Request samples

Content type
application/json
{
  • "template": "string",
  • "path": "string",
  • "folder": "string",
  • "timezone": "string"
}

Response samples

Content type
application/json
{
  • "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"
}

List templates

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.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "folder": "string",
  • "items": [
    ]
}

Add a template

Saves content as name.md in the templates folder. A taken name answers 409 path_taken. Needs vaults:write, sync, or templates:edit.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
Request Body schema: application/json
required
name
required
string [ 1 .. 255 ] characters

The template's name; ".md" is added.

content
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "content": "string"
}

Response samples

Content type
application/json
{
  • "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"
}

Replace a template's text

As updating a note, for a file in the templates folder (others answer 404 template_not_found). Needs vaults:write, sync, or templates:edit.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
file_id
required
string <uuid>
Request Body schema: application/json
required
content
required
string
base_version_id
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "content": "string",
  • "base_version_id": "330601a7-a4c3-4e92-beac-4d56d32a4b5d"
}

Response samples

Content type
application/json
{
  • "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"
}

Delete a template

It stays in version history and can be restored. Needs vaults:write, sync, or templates:edit.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
file_id
required
string <uuid>
query Parameters
base_version_id
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

webhooks

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))
}

List a vault's webhooks

Needs administrator access to the vault.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Add a webhook or integration

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.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
Request Body schema: application/json
required
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. webhook is a custom endpoint. AI meeting notetakers (read_ai, fathom, fireflies, tldv, otter, granola, circleback, avoma, meetgeek) send finished meetings. google_chat, webex, and ntfy could only notify and can no longer be added.

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

telegram: the bot's token from @BotFather.

chat_id
string <= 40 characters

telegram: the chat, group, or channel (-100… or @name) the bot posts to.

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

slack: the app's signing secret (Basic Information); notetakers: the webhook's signing secret.

public_key
string <= 200 characters

discord: the application's public key (hex).

application_id
string <= 40 characters

discord: the application ID; with bot_token, Granite registers the slash commands.

inbound_token
string <= 200 characters

teams: the outgoing webhook's security token; mattermost, rocket_chat, zulip: the webhook's token; fireflies, granola, meetgeek: the API key meetings are fetched with.

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"

Responses

Request samples

Content type
application/json
{
  • "kind": "slack",
  • "url": "string",
  • "bot_token": "string",
  • "chat_id": "string",
  • "actions": [
    ],
  • "folder": "string",
  • "signing_secret": "string",
  • "public_key": "string",
  • "application_id": "string",
  • "inbound_token": "string",
  • "description": "string",
  • "events": [
    ]
}

Response samples

Content type
application/json
{
  • "webhook": {
    },
  • "secret": "string",
  • "action_key": "string"
}

Get a webhook

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
webhook_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "vault_id": "432b199b-1f71-42bf-ba0b-33d512afa9de",
  • "kind": "slack",
  • "url": "string",
  • "description": "string",
  • "events": [
    ],
  • "actions": [
    ],
  • "folder": "string",
  • "inbound_url": "string",
  • "ready": true,
  • "last_inbound_at": "2019-08-24T14:15:22Z",
  • "granite_bot": true,
  • "chats": [
    ],
  • "active": true,
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

Change a webhook

Omitted fields keep their value. rotate_secret returns a new secret once.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
webhook_id
required
string <uuid>
Request Body schema: application/json
required
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

slack: the app's signing secret (Basic Information); notetakers: the webhook's signing secret.

public_key
string <= 200 characters

discord: the application's public key (hex).

application_id
string <= 40 characters

discord: the application ID; with bot_token, Granite registers the slash commands.

inbound_token
string <= 200 characters

teams: the outgoing webhook's security token; mattermost, rocket_chat, zulip: the webhook's token; fireflies, granola, meetgeek: the API key meetings are fetched with.

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

Responses

Request samples

Content type
application/json
{
  • "url": "string",
  • "bot_token": "string",
  • "chat_id": "string",
  • "actions": [
    ],
  • "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
}

Response samples

Content type
application/json
{
  • "webhook": {
    },
  • "secret": "string",
  • "action_key": "string"
}

Delete a webhook

Its pending deliveries and delivery log are deleted too.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
webhook_id
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Connect a chat to Granite's bot

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.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
webhook_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "code": "string",
  • "url": "string",
  • "group_url": "string",
  • "expires_at": "2019-08-24T14:15:22Z"
}

Disconnect a chat

Commands from the chat no longer reach Granite.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
webhook_id
required
string <uuid>
chat_id
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Send a test event

Queues a ping event, sent right away, so you can check the connection.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
webhook_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "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": {
    }
}

The delivery log

Deliveries, newest first, with the outcome of their latest attempt.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
webhook_id
required
string <uuid>
query Parameters
cursor
string <= 512 characters

Opaque cursor from a previous page's next_cursor.

limit
integer <int32> [ 1 .. 200 ]
Default: 50

Maximum items to return.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string"
}

Send a delivery again

Creates a new delivery of the same event (same event id), sent right away.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
webhook_id
required
string <uuid>
delivery_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "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": {
    }
}

oauth

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.

Check an app's authorization request

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.

Authorizations:
bearerAuth
query Parameters
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

Responses

Response samples

Content type
application/json
{
  • "client_id": "string",
  • "client_name": "string",
  • "client_uri": "string",
  • "logo_uri": "string",
  • "redirect_host": "string",
  • "scopes": [
    ],
  • "error_redirect": "string"
}

Allow or deny an app

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.

Authorizations:
bearerAuth
Request Body schema: application/json
required
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 > ]

Responses

Request samples

Content type
application/json
{
  • "request": {
    },
  • "approve": true,
  • "scopes": [
    ],
  • "vault_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "redirect_to": "string"
}

Apps you allowed to use your vaults

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Disconnect an app

Its access ends at once; it has to ask again.

Authorizations:
bearerAuth
path Parameters
grant_id
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

workspaces

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.

People in my workspaces

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.

Authorizations:
bearerAuth
query Parameters
q
required
string [ 1 .. 100 ] characters

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Your workspaces

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create a workspace

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).

Authorizations:
bearerAuth
Request Body schema: application/json
required
name
required
string [ 1 .. 100 ] characters
slug
string^[a-z0-9][a-z0-9-]{1,47}$

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "slug": "string"
}

Response samples

Content type
application/json
{
  • "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"
}

Get a workspace

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "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"
}

Change a workspace

Admins.

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>
Request Body schema: application/json
required
name
string [ 1 .. 100 ] characters
domain_capture
boolean
Deprecated

Only false is accepted; workspaces are joined by invitation only.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "domain_capture": true
}

Response samples

Content type
application/json
{
  • "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"
}

Delete a workspace

The owner. Its vaults and keys are destroyed after the recovery window.

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Members

Members and above (the directory). Owners and admins also see each person's two-step verification, last sign-in, and storage.

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Download a member's personal vaults

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.

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>
user_id
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Delete a member's account

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.

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>
user_id
required
string <uuid>
Request Body schema: application/json
required
transfer_to
string <uuid>

Another member above Guest who receives the personal vaults.

Responses

Request samples

Content type
application/json
{
  • "transfer_to": "e54cab72-cb73-43f0-9b9f-9dd0d9bd5cd7"
}

Response samples

Content type
application/json
{
  • "moved": [
    ]
}

Change a member's role

Admins manage members and guests; only the owner manages admins.

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>
user_id
required
string <uuid>
Request Body schema: application/json
required
role
required
string
Enum: "admin" "member" "guest"

Responses

Request samples

Content type
application/json
{
  • "role": "admin"
}

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Remove a member

Admins (only the owner removes admins). Removing yourself is leaving.

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>
user_id
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Transfer ownership

The owner; they become an admin.

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>
Request Body schema: application/json
required
user_id
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
}

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Leave a workspace

The owner must transfer ownership first.

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Join through your email domain (retired) Deprecated

Workspaces are joined by invitation only; always 404, as for a workspace you are not in. Kept for older apps.

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Pending invitations

Admins.

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Invite someone

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.

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>
Request Body schema: application/json
required
email
string <= 254 characters
role
required
string
Enum: "admin" "member" "guest"

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "role": "admin"
}

Response samples

Content type
application/json
{
  • "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"
}

Revoke an invitation

Admins.

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>
invitation_id
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Claimed email domains

Admins.

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Claim an email domain

Admins. Add the returned TXT record to the domain's DNS, then verify.

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>
Request Body schema: application/json
required
domain
required
string <= 253 characters

Responses

Request samples

Content type
application/json
{
  • "domain": "string"
}

Response samples

Content type
application/json
{
  • "domain": "string",
  • "txt_record": "string",
  • "verified_at": "2019-08-24T14:15:22Z"
}

Drop a claimed domain

Admins.

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>
domain
required
string <= 253 characters

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Verify a domain

Admins. Answers 409 domain_not_verified until the TXT record is visible.

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>
domain
required
string <= 253 characters

Responses

Response samples

Content type
application/json
{
  • "domain": "string",
  • "txt_record": "string",
  • "verified_at": "2019-08-24T14:15:22Z"
}

Workspaces you can join (retired) Deprecated

Workspaces are joined by invitation only, so this list is always empty. Kept for older apps.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

What an invitation is for

Does not need sign-in. The token is sent in the body so it stays out of logs.

Request Body schema: application/json
required
token
required
string <= 200 characters

Responses

Request samples

Content type
application/json
{
  • "token": "string"
}

Response samples

Content type
application/json
{
  • "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9",
  • "workspace_name": "string",
  • "role": "string",
  • "email": "string"
}

Accept an invitation

Email invitations work only for the invited, verified address.

Authorizations:
bearerAuth
Request Body schema: application/json
required
token
required
string <= 200 characters

Responses

Request samples

Content type
application/json
{
  • "token": "string"
}

Response samples

Content type
application/json
{
  • "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"
}

Groups

Members and above.

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Create a group

Admins.

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>
Request Body schema: application/json
required
name
required
string [ 1 .. 100 ] characters

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "members": 0
}

Rename a group

Admins.

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>
group_id
required
string <uuid>
Request Body schema: application/json
required
name
required
string [ 1 .. 100 ] characters

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "name": "string",
  • "members": 0
}

Delete a group

Admins. Its grants stop applying.

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>
group_id
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

A group's members

Members and above.

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>
group_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Add a member to a group

Admins. Takes effect on the member's next request.

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>
group_id
required
string <uuid>
Request Body schema: application/json
required
user_id
required
string <uuid>

Responses

Request samples

Content type
application/json
{
  • "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5"
}

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Remove a member from a group

Admins.

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>
group_id
required
string <uuid>
user_id
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

The workspace's audit log

Admins. Newest first. Filters combine.

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>
query Parameters
cursor
string <= 512 characters

Opaque cursor from a previous page's next_cursor.

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>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "next_cursor": "string"
}

Download the audit log

Admins. CSV, or JSON with one event per line. Up to 100,000 events, newest first.

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>
query Parameters
format
required
string
Enum: "csv" "json"
action
string <= 100 characters
since
string <date-time>
until
string <date-time>

Responses

Response samples

Content type
No sample

The workspace's single sign-on connection

Admins. 404 when SSO is not set up.

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "protocol": "oidc",
  • "issuer": "string",
  • "client_id": "string",
  • "saml": {
    },
  • "jit_role": "member",
  • "enforced": true,
  • "tested_at": "2019-08-24T14:15:22Z",
  • "redirect_url": "string"
}

Connect an identity provider (OpenID Connect or SAML 2.0)

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.

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>
Request Body schema: application/json
required
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

Responses

Request samples

Content type
application/json
{
  • "protocol": "oidc",
  • "issuer": "string",
  • "client_id": "string",
  • "idp_metadata": "string",
  • "idp_metadata_url": "string",
  • "client_secret": "string",
  • "jit_role": "member",
  • "enforced": true
}

Response samples

Content type
application/json
{
  • "protocol": "oidc",
  • "issuer": "string",
  • "client_id": "string",
  • "saml": {
    },
  • "jit_role": "member",
  • "enforced": true,
  • "tested_at": "2019-08-24T14:15:22Z",
  • "redirect_url": "string"
}

Remove single sign-on

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

The workspace's SCIM provisioning

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.

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "enabled": true,
  • "base_url": "string",
  • "token_prefix": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "last_used_at": "2019-08-24T14:15:22Z"
}

Create or replace the SCIM token

Admins. The token is shown only here; give it to the identity provider with base_url.

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "token": "string",
  • "base_url": "string"
}

Turn SCIM provisioning off

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

The workspace's security policy

Admins.

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "require_two_factor": true,
  • "session_hours": 0,
  • "clients": [
    ],
  • "mcp": "on",
  • "knowledge_base": true,
  • "drive": true
}

Change the workspace's security policy

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.

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>
Request Body schema: application/json
required
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 (api covers API tokens, OAuth apps, and the command line).

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).

Responses

Request samples

Content type
application/json
{
  • "require_two_factor": true,
  • "session_hours": 0,
  • "clients": [
    ],
  • "mcp": "on",
  • "knowledge_base": true,
  • "drive": true
}

Response samples

Content type
application/json
{
  • "require_two_factor": true,
  • "session_hours": 0,
  • "clients": [
    ],
  • "mcp": "on",
  • "knowledge_base": true,
  • "drive": true
}

Where audit events are streamed

Admins. 404 when there is no stream.

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "url": "string",
  • "secret": "string",
  • "last_error": "string"
}

Stream audit events to an endpoint

Admins. New events are POSTed in batches ({"workspace_id", "events": [...]}) within a minute, signed like webhooks (Granite-Signature). The secret is returned only here.

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>
Request Body schema: application/json
required
url
required
string <= 2000 characters

Responses

Request samples

Content type
application/json
{
  • "url": "string"
}

Response samples

Content type
application/json
{
  • "url": "string",
  • "secret": "string",
  • "last_error": "string"
}

Stop streaming audit events

Authorizations:
bearerAuth
path Parameters
workspace_id
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

comments

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.

A note's comments

Oldest first; replies have parent_id.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
file_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Comment on a note

Needs comment access to the note. mentions lists people to notify (those who cannot read the note are skipped).

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
file_id
required
string <uuid>
Request Body schema: application/json
required
body
required
string [ 1 .. 10000 ] characters
object (CommentAnchor)
parent_id
string <uuid>
mentions
Array of strings <uuid> <= 50 items [ items <uuid > ]

Responses

Request samples

Content type
application/json
{
  • "body": "string",
  • "anchor": {
    },
  • "parent_id": "1c6ca187-e61f-4301-8dcb-0e9749e89eef",
  • "mentions": [
    ]
}

Response samples

Content type
application/json
{
  • "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": {
    },
  • "resolved_at": "2019-08-24T14:15:22Z",
  • "edited_at": "2019-08-24T14:15:22Z",
  • "deleted": true,
  • "created_at": "2019-08-24T14:15:22Z"
}

Edit or resolve a comment

Only the author edits body; anyone who may comment resolves a thread.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
comment_id
required
string <uuid>
Request Body schema: application/json
required
body
string [ 1 .. 10000 ] characters
resolved
boolean

Responses

Request samples

Content type
application/json
{
  • "body": "string",
  • "resolved": true
}

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Delete a comment

The author or a vault admin. Replies stay.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
comment_id
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Your notifications

Authorizations:
bearerAuth
query Parameters
cursor
string <= 512 characters

Opaque cursor from a previous page's next_cursor.

limit
integer <int32> [ 1 .. 200 ]
Default: 50

Maximum items to return.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "unread": 0,
  • "next_cursor": "string"
}

Mark notifications read

The listed ones, or all when ids is empty.

Authorizations:
bearerAuth
Request Body schema: application/json
required
ids
Array of strings <uuid> <= 200 items [ items <uuid > ]

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

search

Full-text search over notes.

Full-text search in a vault

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.

Authorizations:
bearerAuth
query Parameters
vault_id
required
string <uuid>
q
required
string [ 1 .. 500 ] characters
limit
integer [ 1 .. 50 ]
Default: 20

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "pending": 0
}

knowledge base

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.

Whether the vault and which folders are in the knowledge base

Vault admins.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "included": true,
  • "excluded_folders": [
    ],
  • "exclude_drive": true
}

Choose whether the vault and which folders are in the knowledge base

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.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "included": true,
  • "excluded_folders": [
    ],
  • "exclude_drive": true
}

Response samples

Content type
application/json
{
  • "included": true,
  • "excluded_folders": [
    ],
  • "exclude_drive": true
}

How far the vault's indexing has got

Vault admins.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "available": true,
  • "indexed": true,
  • "documents": 0,
  • "chunks": 0,
  • "pending": 0,
  • "last_indexed_at": "2019-08-24T14:15:22Z",
  • "failures": [
    ]
}

Index the vault again

Vault admins. Queues every file; unchanged files are skipped quickly, failed ones are tried again.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "queued": 0
}

Search the knowledge base

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.

Authorizations:
bearerAuth
Request Body schema: application/json
required
query
required
string [ 1 .. 2000 ] characters
vault_ids
Array of strings <uuid> <= 100 items [ items <uuid > ]
limit
integer [ 1 .. 50 ]
Default: 10

Responses

Request samples

Content type
application/json
{
  • "query": "string",
  • "vault_ids": [
    ],
  • "limit": 10
}

Response samples

Content type
application/json
{
  • "passages": [
    ],
  • "pending": 0
}

publish

Public pages of published notes.

Publish a note as a public page

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).

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
file_id
required
string <uuid>
Request Body schema: application/json
required
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.

Responses

Request samples

Content type
application/json
{
  • "slug": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
  • "path": "string",
  • "slug": "string",
  • "protected": true
}

Take a note's page down

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
file_id
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Published notes in a vault

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

note-shares

One note shared for editing with someone, by email.

People a note is shared with

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
file_id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Share a note for editing by email

Invites someone to edit one note of a personal vault (they see nothing else in it). An email with a link goes to the address. Needs vault admin access and a plan with note sharing (plan_limit_note_sharing); the invitee needs such a plan too before the note opens for them. Workspace vaults share through grants instead (workspace_vault). Sharing again with the same address returns the existing share.

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
file_id
required
string <uuid>
Request Body schema: application/json
required
email
required
string <email> <= 320 characters

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "file_id": "8a0cfb4f-ddc9-436d-91bb-75133c583767",
  • "email": "string",
  • "access": "write",
  • "created_at": "2019-08-24T14:15:22Z"
}

Stop sharing a note with someone

Authorizations:
bearerAuth
path Parameters
vault_id
required
string <uuid>
file_id
required
string <uuid>
share_id
required
string <uuid>

Responses

Response samples

Content type
application/problem+json
{
  • "title": "string",
  • "status": 0,
  • "detail": "string",
  • "instance": "string",
  • "code": "string",
  • "request_id": "string",
  • "errors": [
    ]
}

Notes others shared with me

Notes shared with the caller's verified email. available is false when a plan stands in the way (reason): the caller needs to upgrade, or the owner's plan no longer shares.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "items": [
    ]
}