syncSpecWithCollection
Idempotent
Initiates an asynchronous sync of an OpenAPI specification with its linked Postman collection. Returns HTTP 202 Accepted status.
Instructions
Syncs an API specification linked to a collection. This is an asynchronous endpoint that returns an HTTP `202 Accepted` response.
Note:
This endpoint only supports the OpenAPI 2.0, 3.0, and 3.1 specification types.
This endpoint only supports the OpenAPI 2.0 and 3.0 specification types.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| specId | Yes | The spec's ID. | |
| collectionUid | Yes | The collection's unique ID. |
Implementation Reference
- The main handler function that executes the tool logic. It makes a PUT request to `/specs/{specId}/synchronizations` with an optional `collectionUid` query parameter to sync an API specification with a collection.
export async function handler( args: z.infer<typeof parameters>, extra: { client: PostmanAPIClient; headers?: IsomorphicHeaders; serverContext?: ServerContext } ): Promise<CallToolResult> { try { const endpoint = `/specs/${args.specId}/synchronizations`; const query = new URLSearchParams(); if (args.collectionUid !== undefined) query.set('collectionUid', String(args.collectionUid)); const url = query.toString() ? `${endpoint}?${query.toString()}` : endpoint; const options: any = { headers: extra.headers, }; const result = await extra.client.put(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); } } - Zod schema defining the tool's parameters: specId (string) and collectionUid (string).
export const parameters = z.object({ specId: z.string().describe("The spec's ID."), collectionUid: z.string().describe("The collection's unique ID."), }); - Annotations for the tool: title, readOnlyHint=false, destructiveHint=false, idempotentHint=true.
export const annotations = { title: 'Syncs an API specification linked to a collection. This is an asynchronous endpoint that returns an HTTP \\`202 Accepted\\` response.', readOnlyHint: false, destructiveHint: false, idempotentHint: true, }; - src/enabledResources.ts:1-161 (registration)Tool is listed in the `full` enabled resources array (line 14) and in the `minimal` enabled resources array (line 193), meaning it's available in both full and minimal tool sets.
const full = [ // Collections 'createCollection', 'deleteCollection', 'generateCollection', 'getCollection', 'getCollections', 'patchCollection', 'putCollection', 'getCollectionTags', 'updateCollectionTags', 'getCollectionUpdatesTasks', 'syncCollectionWithSpec', 'syncSpecWithCollection', 'generateSpecFromCollection', 'getGeneratedCollectionSpecs', 'getSpecCollections', // Collection Forks 'getCollectionForks', 'getSourceCollectionStatus', 'getCollectionsForkedByUser', 'pullCollectionChanges', 'createCollectionFork', 'mergeCollectionFork', // Collection Folders 'createCollectionFolder', 'deleteCollectionFolder', 'getCollectionFolder', 'updateCollectionFolder', 'transferCollectionFolders', // Collection Requests 'createCollectionRequest', 'deleteCollectionRequest', 'getCollectionRequest', 'updateCollectionRequest', 'transferCollectionRequests', // Collection Responses 'createCollectionResponse', 'deleteCollectionResponse', 'getCollectionResponse', 'updateCollectionResponse', 'transferCollectionResponses', // Collection Runner 'runCollection', // Comments 'createCollectionComment', 'deleteCollectionComment', 'getCollectionComments', 'updateCollectionComment', 'updateApiCollectionComment', 'createFolderComment', 'deleteFolderComment', 'getFolderComments', 'updateFolderComment', 'createRequestComment', 'deleteRequestComment', 'getRequestComments', 'updateRequestComment', 'createResponseComment', 'deleteResponseComment', 'getResponseComments', 'updateResponseComment', 'resolveCommentThread', // Environments 'createEnvironment', 'deleteEnvironment', 'getEnvironment', 'getEnvironments', 'patchEnvironment', 'putEnvironment', // Mocks 'createMock', 'deleteMock', 'getMock', 'getMocks', 'updateMock', 'publishMock', 'unpublishMock', // Monitors 'createMonitor', 'deleteMonitor', 'getMonitor', 'getMonitors', 'updateMonitor', 'runMonitor', // Specs 'createSpec', 'deleteSpec', 'getSpec', 'getAllSpecs', 'getSpecDefinition', 'updateSpecProperties', 'createSpecFile', 'getSpecFile', 'getSpecFiles', 'updateSpecFile', // Workspaces 'createWorkspace', 'deleteWorkspace', 'getWorkspace', 'getWorkspaces', 'updateWorkspace', 'getWorkspaceGlobalVariables', 'updateWorkspaceGlobalVariables', 'getWorkspaceTags', 'updateWorkspaceTags', // PAN (Private API Network) 'listPrivateNetworkWorkspaces', 'listPrivateNetworkAddRequests', 'removeWorkspaceFromPrivateNetwork', 'addWorkspaceToPrivateNetwork', 'respondPrivateNetworkAddRequest', // // Documentation 'publishDocumentation', 'unpublishDocumentation', // Tasks and Status 'getAsyncSpecTaskStatus', 'getStatusOfAnAsyncApiTask', // User and Tags 'getAuthenticatedUser', 'getTaggedEntities', // Code Generation 'getCodeGenerationInstructions', // Transfer 'transferCollectionFolders', 'transferCollectionResponses', 'transferCollectionResponses', // 'asyncMergePullCollectionFork' skipped // 'asyncMergePullCollectionTaskStatus' skipped // Duplicate Collection 'duplicateCollection', 'getDuplicateCollectionTaskStatus', 'deleteApiCollectionComment', 'deleteSpecFile', 'getEnabledTools', 'searchPostmanElementsInPublicNetwork', 'searchPostmanElementsInPrivateNetwork', // Analytics 'getAnalyticsData', 'getAnalyticsMetadata', ] as const; - The complete module file with exports: method='syncSpecWithCollection', description, parameters (zod schema), annotations, and handler function.
import { z } from 'zod'; import { PostmanAPIClient } from '../clients/postman.js'; import { IsomorphicHeaders, CallToolResult } from '@modelcontextprotocol/sdk/types.js'; import { ServerContext, asMcpError, McpError } from './utils/toolHelpers.js'; export const method = 'syncSpecWithCollection'; export const description = 'Syncs an API specification linked to a collection. This is an asynchronous endpoint that returns an HTTP \\`202 Accepted\\` response.\n\n**Note:**\n\n- This endpoint only supports the OpenAPI 2.0, 3.0, and 3.1 specification types.\n- This endpoint only supports the OpenAPI 2.0 and 3.0 specification types.\n'; export const parameters = z.object({ specId: z.string().describe("The spec's ID."), collectionUid: z.string().describe("The collection's unique ID."), }); export const annotations = { title: 'Syncs an API specification linked to a collection. This is an asynchronous endpoint that returns an HTTP \\`202 Accepted\\` response.', readOnlyHint: false, destructiveHint: false, idempotentHint: true, }; export async function handler( args: z.infer<typeof parameters>, extra: { client: PostmanAPIClient; headers?: IsomorphicHeaders; serverContext?: ServerContext } ): Promise<CallToolResult> { try { const endpoint = `/specs/${args.specId}/synchronizations`; const query = new URLSearchParams(); if (args.collectionUid !== undefined) query.set('collectionUid', String(args.collectionUid)); const url = query.toString() ? `${endpoint}?${query.toString()}` : endpoint; const options: any = { headers: extra.headers, }; const result = await extra.client.put(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); } }