get_story_versions

Instructions

Implementation Reference

• src/tools/stories.ts:458-494 (handler)

  The handler function for the 'get_story_versions' tool. It builds request params (by_story_id, version_id, by_release_id, page, per_page, show_content), calls apiGet('/story_versions', params), and returns the response with versions array and pagination info.

    async ({ by_story_id, version_id, by_release_id, page, per_page, show_content }) => {
      try {
        const params: Record<string, string> = {
          by_story_id: String(by_story_id),
          page: String(page),
          per_page: String(Math.min(per_page, 100)),
        };
  
        if (version_id !== undefined) {
          params.version_id = String(version_id);
        }
        if (by_release_id !== undefined) {
          params.by_release_id = String(by_release_id);
        }
        if (show_content) {
          params.show_content = '1';
        }
  
        const data = await apiGet<{ story_versions: Array<Record<string, unknown>>; total?: number }>(
          '/story_versions',
          params
        );
  
        return createJsonResponse({
          versions: data.story_versions || [],
          page,
          per_page: Math.min(per_page, 100),
          total: data.total ?? null,
        });
      } catch (error) {
        if (error instanceof APIError) {
          return createErrorResponse(error);
        }
        throw error;
      }
    }
  );

• src/tools/stories.ts:450-457 (schema)

  Zod schema for input validation of the 'get_story_versions' tool. Defines parameters: by_story_id (required number), version_id (optional number), by_release_id (optional number), page (optional number, default 1), per_page (optional number, default 25, max 100), show_content (optional boolean, default false).

  {
    by_story_id: z.number().describe('Story ID to get versions for'),
    version_id: z.number().optional().describe('Specific version ID to retrieve'),
    by_release_id: z.number().optional().describe('Filter by release ID'),
    page: z.number().optional().default(1).describe('Page number'),
    per_page: z.number().optional().default(25).describe('Items per page (max 100)'),
    show_content: z.boolean().optional().default(false).describe('Include content in response'),
  },

• src/tools/stories.ts:447-494 (registration)

  Registration of the 'get_story_versions' tool via server.tool(). The tool is registered with name, description, schema, and handler inside the registerStories() function.

  server.tool(
    'get_story_versions',
    'Retrieves versions (revisions) of stories.',
    {
      by_story_id: z.number().describe('Story ID to get versions for'),
      version_id: z.number().optional().describe('Specific version ID to retrieve'),
      by_release_id: z.number().optional().describe('Filter by release ID'),
      page: z.number().optional().default(1).describe('Page number'),
      per_page: z.number().optional().default(25).describe('Items per page (max 100)'),
      show_content: z.boolean().optional().default(false).describe('Include content in response'),
    },
    async ({ by_story_id, version_id, by_release_id, page, per_page, show_content }) => {
      try {
        const params: Record<string, string> = {
          by_story_id: String(by_story_id),
          page: String(page),
          per_page: String(Math.min(per_page, 100)),
        };
  
        if (version_id !== undefined) {
          params.version_id = String(version_id);
        }
        if (by_release_id !== undefined) {
          params.by_release_id = String(by_release_id);
        }
        if (show_content) {
          params.show_content = '1';
        }
  
        const data = await apiGet<{ story_versions: Array<Record<string, unknown>>; total?: number }>(
          '/story_versions',
          params
        );
  
        return createJsonResponse({
          versions: data.story_versions || [],
          page,
          per_page: Math.min(per_page, 100),
          total: data.total ?? null,
        });
      } catch (error) {
        if (error instanceof APIError) {
          return createErrorResponse(error);
        }
        throw error;
      }
    }
  );

• src/tools/index.ts:96-96 (registration)

  The registerStories(server) call in registerAllTools() which triggers registration of all story tools including 'get_story_versions'.

  registerStories(server);

• src/utils/api.ts:180-190 (helper)

  The apiGet helper function used by the handler to make GET requests to the Storyblok Management API. It builds the URL with query params and returns the parsed response.

  export async function apiGet<T = unknown>(
    path: string,
    params: Record<string, string> = {}
  ): Promise<T> {
    const url = buildUrlWithParams(buildManagementUrl(path), params);
    const response = await fetch(url, {
      method: 'GET',
      headers: getManagementHeaders(),
    });
    return handleResponse<T>(response, url);
  }