createSpecFile
Creates an API specification file in Postman. Provide a spec ID, file path, and stringified content to generate a new spec file with default type and folder support.
Instructions
Creates an API specification file.
Note:
If the file path contains a `/` (forward slash) character, then a folder is created. For example, if the path is the `components/schemas.json` value, then a `components` folder is created with the `schemas.json` file inside.
Creating a spec file assigns it the `DEFAULT` file type.
Multi-file specifications can only have one root file.
Files cannot exceed a maximum of 10 MB in size.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| specId | Yes | The spec's ID. | |
| path | Yes | The file's path. Accepts JSON or YAML files. | |
| content | Yes | The file's stringified contents. |
Implementation Reference
- src/tools/createSpecFile.ts:21-52 (handler)The main tool logic: constructs a POST request to /specs/{specId}/files with path and content, sends it via PostmanAPIClient, and returns the result.
export async function handler( args: z.infer<typeof parameters>, extra: { client: PostmanAPIClient; headers?: IsomorphicHeaders; serverContext?: ServerContext } ): Promise<CallToolResult> { try { const endpoint = `/specs/${args.specId}/files`; const query = new URLSearchParams(); const url = query.toString() ? `${endpoint}?${query.toString()}` : endpoint; const bodyPayload: any = {}; if (args.path !== undefined) bodyPayload.path = args.path; if (args.content !== undefined) bodyPayload.content = args.content; const options: any = { body: JSON.stringify(bodyPayload), contentType: ContentType.Json, headers: extra.headers, }; const result = await extra.client.post(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/createSpecFile.ts:9-13 (schema)Zod schema for the tool's input parameters: specId (string), path (string), content (string).
export const parameters = z.object({ specId: z.string().describe("The spec's ID."), path: z.string().describe("The file's path. Accepts JSON or YAML files."), content: z.string().describe("The file's stringified contents."), }); - src/tools/createSpecFile.ts:6-6 (schema)Exported method name constant 'createSpecFile' used for tool identification.
export const method = 'createSpecFile'; - src/tools/createSpecFile.ts:14-19 (schema)Annotations for the tool including title, readOnlyHint, destructiveHint, idempotentHint.
export const annotations = { title: 'Creates an API specification file.', readOnlyHint: false, destructiveHint: false, idempotentHint: false, }; - src/index.ts:253-262 (registration)Registration of all tools (including createSpecFile) via server.registerTool() using the module's method, description, inputSchema, annotations, and handler.
// Register all tools using the McpServer registerTool method for (const tool of tools) { server.registerTool( tool.method, { description: tool.description, inputSchema: tool.parameters.shape, annotations: tool.annotations || {}, }, async (args, extra) => {