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.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/granite-md:granite-md-comments-api"curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Granite Comments API
version: 1.0.0
summary: REST API for Granite clients, bots, and integrations.
description: '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/`; `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 ` 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).'
license:
name: Proprietary
identifier: LicenseRef-Proprietary
servers:
- url: https://api.granite.md
description: Production
- url: http://localhost:8080
description: Local development
security:
- bearerAuth: []
tags:
- name: Comments
description: '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.'
paths:
/v1/vaults/{vault_id}/files/{file_id}/comments:
parameters:
- $ref: '#/components/parameters/VaultID'
- $ref: '#/components/parameters/FileID'
get:
operationId: listComments
tags:
- Comments
summary: A note's comments
description: Oldest first; replies have `parent_id`.
responses:
'200':
description: Comments.
content:
application/json:
schema:
$ref: '#/components/schemas/CommentList'
default:
$ref: '#/components/responses/Error'
post:
operationId: createComment
tags:
- Comments
summary: Comment on a note
description: Needs comment access to the note. `mentions` lists people to notify (those who cannot read the note are skipped).
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CommentCreate'
responses:
'201':
description: The comment.
content:
application/json:
schema:
$ref: '#/components/schemas/Comment'
default:
$ref: '#/components/responses/Error'
/v1/vaults/{vault_id}/comments/{comment_id}:
parameters:
- $ref: '#/components/parameters/VaultID'
- name: comment_id
in: path
required: true
schema:
type: string
format: uuid
patch:
operationId: updateComment
tags:
- Comments
summary: Edit or resolve a comment
description: Only the author edits `body`; anyone who may comment resolves a thread.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CommentUpdate'
responses:
'204':
description: Changed.
default:
$ref: '#/components/responses/Error'
delete:
operationId: deleteComment
tags:
- Comments
summary: Delete a comment
description: The author or a vault admin. Replies stay.
responses:
'204':
description: Deleted.
default:
$ref: '#/components/responses/Error'
/v1/me/notifications:
get:
operationId: listNotifications
tags:
- Comments
summary: Your notifications
parameters:
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
responses:
'200':
description: Notifications, newest first.
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationList'
default:
$ref: '#/components/responses/Error'
/v1/me/notifications/read:
post:
operationId: markNotificationsRead
tags:
- Comments
summary: Mark notifications read
description: The listed ones, or all when `ids` is empty.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NotificationsRead'
responses:
'204':
description: Done.
default:
$ref: '#/components/responses/Error'
components:
headers:
RequestID:
description: Identifier of this request, for support and log correlation.
schema:
type: string
schemas:
NotificationList:
type: object
required:
- items
- unread
properties:
items:
type: array
items:
$ref: '#/components/schemas/Notification'
unread:
type: integer
format: int64
next_cursor:
type: string
CommentUpdate:
type: object
properties:
body:
type: string
minLength: 1
maxLength: 10000
resolved:
type: boolean
CommentCreate:
type: object
required:
- body
properties:
body:
type: string
minLength: 1
maxLength: 10000
anchor:
$ref: '#/components/schemas/CommentAnchor'
parent_id:
type: string
format: uuid
mentions:
type: array
maxItems: 50
items:
type: string
format: uuid
CommentAnchor:
type: object
required:
- quote
properties:
quote:
type: string
minLength: 1
maxLength: 2000
prefix:
type: string
maxLength: 200
suffix:
type: string
maxLength: 200
line:
type: integer
CommentList:
type: object
required:
- items
properties:
items:
type: array
items:
$ref: '#/components/schemas/Comment'
Problem:
type: object
description: RFC 9457 problem details.
required:
- type
- title
- status
properties:
type:
type: string
format: uri
examples:
- https://granite.md/problems/conflict
title:
type: string
status:
type: integer
format: int32
detail:
type: string
instance:
type: string
code:
type: string
description: Machine-readable refinement of `type`, for example `version_conflict`.
request_id:
type: string
errors:
type: array
description: Per-field validation errors.
items:
$ref: '#/components/schemas/FieldError'
Notification:
type: object
description: 'Something for the person to know about. `mention`: someone mentioned them in a comment.
`reply`: someone replied in a comment thread they wrote in. `resolved`: a comment thread on
a note they own or edited was resolved. `team_added`: someone added them to a team
(`group_id`, `group_name`, `workspace_id`, `workspace_name`). `shared`: someone shared a
vault, folder, or note with them (`vault_id`, `vault_name`, and `path`: "" for the whole
vault, a folder path with `folder` true, or a note path with `file_id`).
'
required:
- id
- kind
- actor_id
- created_at
properties:
id:
type: string
format: uuid
kind:
type: string
enum:
- mention
- reply
- resolved
- team_added
- shared
actor_id:
type: string
format: uuid
actor_email:
type: string
actor_name:
type: string
actor_avatar_url:
type: string
description: The actor's profile photo path on the API server, if any.
vault_id:
type: string
format: uuid
vault_name:
type: string
file_id:
type: string
format: uuid
path:
type: string
folder:
type: boolean
description: '`shared`: the path is a folder.'
comment_id:
type: string
format: uuid
group_id:
type: string
format: uuid
group_name:
type: string
workspace_id:
type: string
format: uuid
workspace_name:
type: string
read_at:
type: string
format: date-time
created_at:
type: string
format: date-time
NotificationsRead:
type: object
properties:
ids:
type: array
maxItems: 200
items:
type: string
format: uuid
Comment:
type: object
required:
- id
- author_id
- body
- deleted
- created_at
properties:
id:
type: string
format: uuid
parent_id:
type: string
format: uuid
author_id:
type: string
format: uuid
author_email:
type: string
author_name:
type: string
author_avatar_url:
type: string
description: The author's profile photo path on the API server, if any.
body:
type: string
anchor:
$ref: '#/components/schemas/CommentAnchor'
resolved_at:
type: string
format: date-time
edited_at:
type: string
format: date-time
deleted:
type: boolean
created_at:
type: string
format: date-time
FieldError:
type: object
required:
- field
- detail
properties:
field:
type: string
description: JSON path of the invalid field, for example `ops[2].path`.
detail:
type: string
parameters:
VaultID:
name: vault_id
in: path
required: true
schema:
type: string
format: uuid
FileID:
name: file_id
in: path
required: true
schema:
type: string
format: uuid
Limit:
name: limit
in: query
required: false
description: Maximum items to return.
schema:
type: integer
format: int32
minimum: 1
maximum: 200
default: 50
Cursor:
name: cursor
in: query
required: false
description: Opaque cursor from a previous page's `next_cursor`.
schema:
type: string
maxLength: 512
responses:
Error:
description: Error response.
headers:
X-Request-ID:
$ref: '#/components/headers/RequestID'
content:
application/problem+json:
schema:
$ref: '#/components/schemas/Problem'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Session access token, personal API token, or OAuth access token.