getTaggedEntities
Read-onlyIdempotent
Retrieve Postman entities (workspaces, APIs, collections) tagged with a specific tag to organize and filter resources.
Instructions
Requires an Enterprise plan. Tagging is only available on Postman Enterprise plans. This tool returns a 404 error on Free, Basic, and Professional accounts.
Gets Postman elements (entities) by a given tag. Tags enable you to organize and search workspaces, APIs, and collections that contain shared tags.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| slug | Yes | The tag's ID within a team or individual (non-team) user scope. | |
| limit | No | The maximum number of tagged elements to return in a single call. | |
| direction | No | The ascending (`asc`) or descending (`desc`) order to sort the results by, based on the time of the entity's tagging. | desc |
| cursor | No | The cursor to get the next set of results in the paginated response. If you pass an invalid value, the API only returns the first set of results. | |
| entityType | No | Filter results for the given entity type. |
Implementation Reference
- src/tools/getTaggedEntities.ts:47-77 (handler)Handler function that calls the Postman API endpoint /tags/{slug}/entities with query parameters (limit, direction, cursor, entityType) to get tagged entities.
export async function handler( args: z.infer<typeof parameters>, extra: { client: PostmanAPIClient; headers?: IsomorphicHeaders; serverContext?: ServerContext } ): Promise<CallToolResult> { try { const endpoint = `/tags/${args.slug}/entities`; const query = new URLSearchParams(); if (args.limit !== undefined) query.set('limit', String(args.limit)); if (args.direction !== undefined) query.set('direction', String(args.direction)); if (args.cursor !== undefined) query.set('cursor', String(args.cursor)); if (args.entityType !== undefined) query.set('entityType', String(args.entityType)); const url = query.toString() ? `${endpoint}?${query.toString()}` : endpoint; const options: any = { headers: extra.headers, }; const result = await extra.client.get(url, options); return { content: [ { type: 'text', text: `${typeof result === 'string' ? result : JSON.stringify(result, null, 2)}`, }, ], }; } catch (e: unknown) { if (e instanceof McpError) { throw e; } throw asMcpError(e); } } - src/tools/getTaggedEntities.ts:9-38 (schema)Zod schema defining the input parameters: slug (required), limit (default 10), direction (default 'desc'), cursor (optional), entityType (optional enum).
export const parameters = z.object({ slug: z .string() .regex(new RegExp('^[a-z][a-z0-9-]*[a-z0-9]+$')) .min(2) .max(64) .describe("The tag's ID within a team or individual (non-team) user scope."), limit: z .number() .int() .lte(50) .describe('The maximum number of tagged elements to return in a single call.') .default(10), direction: z .enum(['asc', 'desc']) .describe( "The ascending (`asc`) or descending (`desc`) order to sort the results by, based on the time of the entity's tagging." ) .default('desc'), cursor: z .string() .describe( 'The cursor to get the next set of results in the paginated response. If you pass an invalid value, the API only returns the first set of results.' ) .optional(), entityType: z .enum(['api', 'collection', 'workspace']) .describe('Filter results for the given entity type.') .optional(), }); - src/enabledResources.ts:136-136 (registration)Registration of 'getTaggedEntities' in the full list of enabled resources.
'getTaggedEntities', - src/enabledResources.ts:186-186 (registration)Registration of 'getTaggedEntities' in the minimal list of enabled resources.
'getTaggedEntities', - src/tools/utils/toolHelpers.ts:10-13 (helper)Helper function used by the handler to convert errors to MCP errors.
export function asMcpError(error: unknown): McpError { const cause = (error as any)?.cause ?? String(error); return new McpError(ErrorCode.InternalError, cause); }