Nestornotes Docs
API v1

Endpoints

API v1 endpoint reference.

All endpoints are under:

/api/v1

Me

GET /me

Returns the profile, enabled scopes, and credit status for the bearer token.

Collections

GET /collections
GET /collections/:id

Requires collections:read.

Collection responses use public camelCase fields and omit internal owner fields:

{
  "id": "collection-id",
  "name": "AI Research",
  "slug": "ai-research",
  "description": "Articles and source updates about AI",
  "nestornotesEmail": "ai-research@nnotes.me",
  "defaultCollection": false,
  "defaultSetNestornotesEmail": null,
  "scheduleType": "daily",
  "scheduleTime": 8,
  "scheduleDay": null,
  "scheduleTimezone": "Europe/Berlin",
  "sendEmailSummaries": true
}

Knowledge

GET /knowledge
GET /knowledge/:id
PATCH /knowledge/:id

GET requires knowledge:read. PATCH requires knowledge:write.

List filters:

  • collection_id
  • object_type
  • summarized
  • bookmarked
  • archived
  • seen
  • created_after
  • created_before
  • updated_after
  • updated_before
  • limit
  • offset

Mutable fields:

{
  "seen": true,
  "bookmarked": true,
  "archived": false,
  "include_in_digest": true
}

Knowledge responses use public camelCase fields and omit internal owner fields:

{
  "id": "knowledge-id",
  "objectId": "article-id",
  "objectType": "article",
  "collectionId": "collection-id",
  "summarized": true,
  "includeInDigest": true,
  "sentInDigest": false,
  "seen": false,
  "bookmarked": true,
  "archived": false,
  "storedInDocuments": false,
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-03T00:00:00.000Z"
}

Tags

POST /knowledge/:id/tags
DELETE /knowledge/:id/tags/:tag_id

Requires tags:write.

Create or attach a tag by name:

{
  "name": "Important"
}

Tag mutation responses return public camelCase link fields and omit owner fields:

{
  "id": "knowledge-tag-link-id",
  "knowledgeId": "knowledge-id",
  "tagId": "tag-id",
  "tag": {
    "id": "tag-id",
    "name": "Important",
    "color": ""
  }
}
POST /search/keyword
POST /search/semantic

Requires search:read.

{
  "query": "recent posts about vector databases",
  "collection_id": "optional-collection-id",
  "limit": 10
}

Semantic search also accepts idempotency_key and consumes one credit.

Search responses return public result DTOs:

{
  "id": "document-id",
  "content": "A matching document snippet",
  "metadata": {
    "object_id": "article-id"
  },
  "similarity": 0.91
}

Typed Content

Typed content endpoints expose the source-specific rows behind knowledge metadata.

GET /articles
GET /articles/:id
GET /emails
GET /emails/:id
GET /rss/items
GET /rss/items/:id
GET /youtube/videos
GET /youtube/videos/:id
GET /x/posts
GET /x/posts/:id
GET /linkedin/posts
GET /linkedin/posts/:id
GET /podcasts/episodes
GET /podcasts/episodes/:id

Required scopes:

EndpointsScope
/articles/**articles:read
/emails/**emails:read
/rss/items/**rss:read
/youtube/videos/**youtube:read
/x/posts/**x:read
/linkedin/posts/**linkedin:read
/podcasts/episodes/**podcasts:read

List filters:

  • collection_id
  • archived
  • bookmarked
  • summarized
  • from
  • to
  • limit
  • offset

Source-specific list filters:

  • RSS items: channel_id
  • YouTube videos: channel_id
  • X posts: account_id
  • LinkedIn posts: source_id
  • Podcast episodes: show_id

Detail ids are profile-scoped item ids for source items: profile_item_id, profile_post_id, or profile_episode_id. Articles use article id; emails use incoming_email_id.

Typed content responses use public camelCase DTO fields. Article lists return metadata state, while article details return summary content:

{
  "id": "article-id",
  "name": "Saved article",
  "collectionName": "AI Research",
  "collectionId": "collection-id",
  "knowledgeMetadataId": "knowledge-id",
  "metadataTags": ["tag-id"],
  "includeInDigest": true,
  "storedInDocuments": false,
  "createdAt": "2026-01-03T00:00:00.000Z"
}

Email list responses omit the full HTML body; email detail responses include htmlEmail:

{
  "incomingEmailId": "email-id",
  "subject": "Product update",
  "emailFrom": "sender@example.com",
  "emailReceivedAt": "2026-01-05T00:00:00.000Z",
  "includeInDigest": true,
  "shortDescription": "A short summary"
}

RSS item responses use profileItemId as the detail id and include worker-owned fetch/fallback status fields:

{
  "profileItemId": "rss-profile-item-id",
  "id": "rss-item-id",
  "rssChannelId": "rss-channel-id",
  "title": "Feed item title",
  "link": "https://example.com/post",
  "pubDate": "2026-01-06T00:00:00.000Z",
  "includeInDigest": true,
  "processingStatus": "summarized",
  "articleFetchStatus": "fetched",
  "fallbackUsed": false,
  "contentSource": "article"
}

YouTube video responses use profileItemId as the detail id and expose public video metadata plus summary state:

{
  "profileItemId": "youtube-profile-item-id",
  "id": "youtube-item-id",
  "videoId": "youtube-video-id",
  "youtubeChannelId": "youtube-channel-id",
  "title": "Video title",
  "publishedAt": "2026-01-06T00:00:00.000Z",
  "thumbnailUrl": "https://img.youtube.com/vi/youtube-video-id/default.jpg",
  "duration": "PT5M",
  "viewCount": 100,
  "includeInDigest": true
}

X, LinkedIn, and podcast responses also expose public source metadata and summary state through camelCase fields. Provider raw blobs are omitted.

{
  "profileItemId": "x-profile-item-id",
  "id": "x-item-id",
  "xAccountId": "x-account-id",
  "title": "X post title",
  "bodyText": "Post body text",
  "postUrl": "https://x.com/example/status/123",
  "sourceStatus": "fetched",
  "sourceUrls": ["https://example.com/source"],
  "includeInDigest": true
}
{
  "profilePostId": "linkedin-profile-post-id",
  "id": "linkedin-post-id",
  "linkedinSourceId": "linkedin-source-id",
  "sourceName": "Example Company",
  "postUrl": "https://www.linkedin.com/feed/update/...",
  "text": "Post text",
  "postedAt": "2026-01-08T00:00:00.000Z",
  "includeInDigest": true
}
{
  "profileEpisodeId": "podcast-profile-episode-id",
  "id": "podcast-episode-id",
  "podcastShowId": "podcast-show-id",
  "showTitle": "Example Podcast",
  "title": "Episode title",
  "publishedAt": "2026-01-09T00:00:00.000Z",
  "transcriptStatus": "completed",
  "transcriptProvider": "assemblyai",
  "includeInDigest": true
}

Credits And Usage

GET /credits
GET /usage

GET /credits requires credits:read and returns the current credit status plus active action costs.

GET /usage requires usage:read.

Credit responses use public camelCase fields:

{
  "status": {
    "creditsRemaining": 10,
    "creditsLimit": 10
  },
  "actionCosts": [
    {
      "actionType": "api_semantic_search",
      "credits": 1,
      "description": "Semantic search"
    }
  ]
}

Usage filters:

  • action_type
  • from
  • to
  • limit
  • offset

Usage responses also use camelCase fields and omit internal owner fields:

{
  "id": "usage-id",
  "actionType": "api_semantic_search",
  "credits": 1,
  "objectType": "api_key",
  "objectId": "api-key-id",
  "idempotencyKey": "idempotency-key",
  "metadata": {},
  "periodStart": "2026-01-01T00:00:00.000Z",
  "periodEnd": "2026-02-01T00:00:00.000Z",
  "createdAt": "2026-01-07T00:00:00.000Z"
}

Errors

API v1 returns stable JSON error envelopes.

MCP Setup

Connect MCP-compatible clients to Nestornotes.

On this page

MeCollectionsKnowledgeTagsSearchTyped ContentCredits And Usage