A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Guru API is how an app or AI agent works with a Guru workspace: searching cards of verified knowledge, creating and updating a card, verifying a card so the team can trust it, and organizing cards into folders and collections. Access is granted through a token sent with HTTP Basic auth, where a user token carries read and write across the collections that person can reach and a collection token is read-only and scoped to a single collection. Guru can also push events to a registered URL when something happens, like a card being created or verified.
How an app or AI agent connects to Guru determines what it can reach. There is a route for making calls, a route for receiving events, and a hosted server that exposes Guru's knowledge to agents, and each is governed by the token behind it and the access that token carries.
The REST API answers at https://api.getguru.com/api/v1/, takes and returns JSON, and pages long lists through a Link header. A call authenticates with HTTP Basic auth, sending a user email and token, or a collection id and token, as the username and password.
Guru posts events to a URL registered for the chosen event types, so an app learns about activity like a card being created, updated, or verified without polling. A single user can create up to 25 webhook subscriptions, and what a subscription can see depends on the creator's Guru role.
Guru's first-party MCP server at https://mcp.api.getguru.com/mcp exposes Guru's knowledge to AI clients like Claude, ChatGPT, and Cursor through the Model Context Protocol. It lets an agent search the knowledge base, ask for verified and cited answers, and create or update cards, and it authenticates with OAuth or an API token.
A user token authenticates as a person and carries read and write access, so it can call GET, POST, PUT, and DELETE. What it reaches depends on that person's authorization: a team admin token sees more than an author token in restricted collections. It is sent with the user's email through HTTP Basic auth.
A collection token is authorized at the level of a single collection and is read-only, so it can call GET methods only and returns results from just that one collection. It is sent with the collection id as the username through HTTP Basic auth.
OAuth 2.0 lets an app or AI client connect on a user's behalf without holding a raw token, and it is the route Guru's MCP server and connected clients use. The resulting access represents the authorizing user.
The Guru API is split into areas an agent can act on, like cards, collections, folders, groups, and people. Each area has its own methods, and a write here changes the knowledge a team relies on.
Read, create, update, and delete cards, verify and unverify them, and read the folders and favorite lists a card sits in.
List, create, and delete the comments on a card.
List the collections a token can reach and read a single collection by id.
List folders, read a folder's items, create and update folders, and delete a folder. Folders replaced the older boards.
Search for cards across a workspace with a query string, and run a richer search that returns cited sources.
List user groups, read a group's members and the collections it can reach, and add or remove a member.
List team members, read and update a person's profile, invite a user to the team, and read the authenticated identity.
List tag categories, read a tag, and create a tag.
List the activity events recorded for a team.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
CardsRead, create, update, and delete cards, verify and unverify them, and read the folders and favorite lists a card sits in.8 | ||||||
| GET | /v1/cards/{cardId}/extended | Get a single card with its extended detail, including content and metadata. | read | read | Current | |
Reachable with a read-only collection token if the card is in that collection, or a user token at the caller's authorization level. Acts oncard Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/cards/extended | Create a card. | write | write | Current | |
Writes need a user token with read/write; a collection token is read-only and cannot create cards. Acts oncard Permission (capability) writeVersionAvailable since the API’s base version Webhook event card-createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v1/cards/{cardId}/extended | Update a card's content or metadata. | write | write | Current | |
Needs a user token with read/write. Acts oncard Permission (capability) writeVersionAvailable since the API’s base version Webhook event card-updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/cards/{cardId} | Delete a card. Returns 204 No Content on success. | write | write | Current | |
Irreversible; needs a user token with read/write. Acts oncard Permission (capability) writeVersionAvailable since the API’s base version Webhook event card-deletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v1/cards/{cardId}/verify | Mark a card as verified, confirming its content is up to date. | write | write | Current | |
Verification is Guru's trust signal; needs a user token with read/write. Acts oncard Permission (capability) writeVersionAvailable since the API’s base version Webhook event card-verifiedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/cards/{cardId}/unverify | Mark a card as unverified, flagging that its content may be out of date. | write | write | Current | |
Needs a user token with read/write. Acts oncard Permission (capability) writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/cards/{cardId}/folders | List the folders a card is on. | read | read | Current | |
A read method; reachable with a read-only collection token for cards in that collection. Acts oncard Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/cards/{cardId}/favoritelists | List the favorite lists that include a card. | read | read | Current | |
A read method. Guru models a favorite as adding a card to a favorite list rather than a single toggle. Acts oncard Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Card commentsList, create, and delete the comments on a card.3 | ||||||
| GET | /v1/cards/{cardId}/comments | List the comments on a card. | read | read | Current | |
A read method; reachable with a read-only collection token for cards in that collection. Acts oncomment Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/cards/{cardId}/comments | Create a comment on a card. | write | write | Current | |
Needs a user token with read/write. Acts oncomment Permission (capability) writeVersionAvailable since the API’s base version Webhook event card-comment-createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/cards/{cardId}/comments/{commentId} | Delete a comment from a card. | write | write | Current | |
Needs a user token with read/write. Acts oncomment Permission (capability) writeVersionAvailable since the API’s base version Webhook event card-comment-deletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CollectionsList the collections a token can reach and read a single collection by id.2 | ||||||
| GET | /v1/collections | List the collections the token can reach. | read | read | Current | |
A read method. A collection token returns only its own collection here; a user token returns all collections the caller can see. Acts oncollection Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/collections/{collectionId} | Find a single collection by its id. | read | read | Current | |
A read method; reachable with a read-only collection token for its own collection. Acts oncollection Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
FoldersList folders, read a folder's items, create and update folders, and delete a folder. Folders replaced the older boards.5 | ||||||
| GET | /v1/folders | List folders. Folders replaced the older boards in the Guru hierarchy. | read | read | Current | |
A read method; reachable with a read-only collection token within that collection. Acts onfolder Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/folders/{folderId}/items | List the items inside a folder. Both cards and other folders can sit in a folder. | read | read | Current | |
A read method; reachable with a read-only collection token within that collection. Acts onfolder Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/folders/{parentId}/action | Create a folder, or add a card to a folder, by posting an action to the parent collection or folder. | write | write | Current | |
The body sets an actionType, such as add, and where to place the item. Needs a user token with read/write. Acts onfolder Permission (capability) writeVersionAvailable since the API’s base version Webhook event card-added-to-boardRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v1/folders/{folderId} | Update a folder's details. | write | write | Current | |
Needs a user token with read/write. Acts onfolder Permission (capability) writeVersionAvailable since the API’s base version Webhook event board-updatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v1/folders/{folderId} | Delete a folder. | write | write | Current | |
Needs a user token with read/write. Acts onfolder Permission (capability) writeVersionAvailable since the API’s base version Webhook event board-deletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SearchSearch for cards across a workspace with a query string, and run a richer search that returns cited sources.2 | ||||||
| GET | /v1/search/query | Search for cards with a query string, filtered through Guru Query Language. A maximum of 50 cards is returned per page. | read | read | Current | |
Results are scoped to what the token can see; a collection token returns only matches in its own collection. Pages through the Link header. Acts onsearch result Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limit50 cards per page SourceOfficial documentation ↗ | ||||||
| POST | /v1/search/keyworddocumentsearch | Search across cards and connected sources, returning results with their sources. | read | read | Current | |
A read method; results are limited to what the token can see. Acts onsearch result Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
GroupsList user groups, read a group's members and the collections it can reach, and add or remove a member.3 | ||||||
| GET | /v1/groups | List the user groups on a team. | read | read | Current | |
A read method; needs a user token with the caller's authorization to see groups. Acts ongroup Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/groups/{groupId}/members | List the members of a user group. | read | read | Current | |
A read method; returns the people in the group. Acts ongroup Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/groups/{groupId}/members | Add a member to a user group. | write | write | Current | |
Changes who can see the collections the group reaches. Needs a user token with admin authorization. Acts ongroup Permission (capability) writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
People & membersList team members, read and update a person's profile, invite a user to the team, and read the authenticated identity.5 | ||||||
| GET | /v1/members | List the members of a team. | read | read | Current | |
A read method; returns each person's name, email, role, and status. Acts onmember Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/members/invite | Invite one or more users to the team by email, with a role. | write | write | Current | |
Must be called as a team admin. The body takes a list of emails and a role, such as MEMBER or AUTHOR; invited people stay PENDING until they accept. Acts onmember Permission (capability) writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/people/{userId} | Get a person's profile. | read | read | Current | |
A read method; returns a single person's profile fields. Acts onperson Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v1/people/{userId} | Update a person's profile. | write | write | Current | |
Needs a user token with admin authorization to change another person's profile. Acts onperson Permission (capability) writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/whoami | Read basic information about the authenticated identity, including the user, the team, any collection, and the token type. | read | read | Current | |
Reachable with any valid token; the tokenType field returns API, SESSION, COLLECTION, OTHER, or UNKNOWN. Acts onidentity Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TagsList tag categories, read a tag, and create a tag.3 | ||||||
| GET | /v1/teams/{teamId}/tagcategories | List the tag categories on a team. | read | read | Current | |
A read method; a tag belongs to a category, and a category belongs to a team. Acts ontag category Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v1/teams/{teamId}/tagcategories/tags/{tagId} | Get a single tag. | read | read | Current | |
A read method; returns one tag's detail. Acts ontag Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v1/teams/{teamId}/tagcategories/tags | Create a tag within a tag category. | write | write | Current | |
Needs a user token with read/write. Acts ontag Permission (capability) writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
AnalyticsList the activity events recorded for a team.1 | ||||||
| GET | /v1/teams/{teamId}/analytics | List the activity events recorded for a team. A maximum of 500 events is returned per page, with optional date-range parameters. | read | read | Current | |
A read method; pages through the Link header when more than 500 events match. Acts onevent Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limit500 events per page SourceOfficial documentation ↗ | ||||||
Guru can notify an app or AI agent when something happens in a workspace, like a card being created, updated, or verified, instead of the app repeatedly asking. Guru posts the event to a URL registered for the chosen events.
| Event | What it signals | Triggered by |
|---|---|---|
card-created | Fires when a card is created. | /v1/cards/extended |
card-updated | Fires when a card's content or metadata is updated. | /v1/cards/{cardId}/extended |
card-deleted | Fires when a card is deleted. | /v1/cards/{cardId} |
card-verified | Fires when a card is marked verified. | /v1/cards/{cardId}/verify |
card-comment-created | Fires when a comment is created on a card. | /v1/cards/{cardId}/comments |
card-comment-deleted | Fires when a comment is deleted from a card. | /v1/cards/{cardId}/comments/{commentId} |
card-added-to-board | Fires when a card is added to a folder. The event keeps the older board name from before folders replaced boards. | /v1/folders/{parentId}/action |
board-updated | Fires when a folder is updated. The event keeps the older board name. | /v1/folders/{folderId} |
board-deleted | Fires when a folder is deleted. The event keeps the older board name. | /v1/folders/{folderId} |
Guru limits how fast an app or AI agent can call, through a per-account request rate that returns a back-off response when exceeded, and it pages long result sets through a link to the next page.
Guru enforces a request rate per account and returns HTTP 429 Too Many Requests when it is exceeded; the documented guidance is to back off and retry after a short wait rather than a published number of requests per minute. The reference pages do not state a per-method cost, so an integration should treat the rate as a shared account budget and smooth out bursts.
Long result sets are paged with a Link header. When more results remain, the response carries a Link header with rel="next-page" holding the URL of the next page, and an integration follows that link until no Link header is returned rather than building the URL by hand. Page size depends on the endpoint, for example search returns at most 50 cards per page and analytics at most 500 events per page.
Responses are JSON. Search returns at most 50 cards per page and the analytics events endpoint at most 500 events per page; other list endpoints set their own page sizes, which the reference notes can change over time.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | Unauthorized | Authentication is missing or invalid, for example a wrong token, or the wrong username for the token type. | Send valid HTTP Basic credentials: the user email with a user token, or the collection id with a collection token. |
| 403 | Forbidden | The token is valid but does not have the access the call needs, for example a read-only collection token attempting a write, or a non-admin token inviting a user. | Use a user token at the right authorization level, or an admin token for member and group changes. |
| 404 | Not Found | The path is wrong, or the resource is not visible to the token, for example a card outside the collection a collection token is scoped to. | Check the path and confirm the token can reach the resource. |
| 429 | Too Many Requests | The account's request rate was exceeded. | Back off for a short period, then retry. Spread out bursts of calls. |
Guru runs a single, continuously updated version of its API. There is no dated version to pin, and every path sits under the v1 prefix.
Guru exposes one REST API under the v1 path prefix, with no dated versions to pin and no version header to send. Changes ship to the same live API, and new endpoints are announced through the Guru Developer Network. Notable additions include the move from boards to folders and the first-party MCP server.
There is no version header to set; an integration calls the current API directly.
Guru Developer Network ↗Bollard AI sits between a team's AI agents and Guru. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.