get_snapshots

Instructions

Implementation Reference

• archivebox_api/archivebox_mcp.py:147-268 (handler)

  MCP tool registration and handler function for 'get_snapshots'. Defines input schema via Pydantic Fields, creates Api client, calls underlying get_snapshots, and returns JSON response.

  @mcp.tool(
      exclude_args=[
          "archivebox_url",
          "username",
          "password",
          "token",
          "api_key",
          "verify",
      ],
      tags={"core"},
  )
  def get_snapshots(
      id: Optional[str] = Field(None, description="Filter by snapshot ID"),
      abid: Optional[str] = Field(None, description="Filter by snapshot abid"),
      created_by_id: Optional[str] = Field(None, description="Filter by creator ID"),
      created_by_username: Optional[str] = Field(
          None, description="Filter by creator username"
      ),
      created_at__gte: Optional[str] = Field(
          None, description="Filter by creation date >= (ISO 8601)"
      ),
      created_at__lt: Optional[str] = Field(
          None, description="Filter by creation date < (ISO 8601)"
      ),
      created_at: Optional[str] = Field(
          None, description="Filter by exact creation date (ISO 8601)"
      ),
      modified_at: Optional[str] = Field(
          None, description="Filter by exact modification date (ISO 8601)"
      ),
      modified_at__gte: Optional[str] = Field(
          None, description="Filter by modification date >= (ISO 8601)"
      ),
      modified_at__lt: Optional[str] = Field(
          None, description="Filter by modification date < (ISO 8601)"
      ),
      search: Optional[str] = Field(
          None, description="Search across url, title, tags, id, abid, timestamp"
      ),
      url: Optional[str] = Field(None, description="Filter by URL (exact)"),
      tag: Optional[str] = Field(None, description="Filter by tag name (exact)"),
      title: Optional[str] = Field(None, description="Filter by title (icontains)"),
      timestamp: Optional[str] = Field(
          None, description="Filter by timestamp (startswith)"
      ),
      bookmarked_at__gte: Optional[str] = Field(
          None, description="Filter by bookmark date >= (ISO 8601)"
      ),
      bookmarked_at__lt: Optional[str] = Field(
          None, description="Filter by bookmark date < (ISO 8601)"
      ),
      with_archiveresults: bool = Field(
          False, description="Include archiveresults in response"
      ),
      limit: int = Field(10, description="Number of results to return"),
      offset: int = Field(0, description="Offset for pagination"),
      page: int = Field(0, description="Page number for pagination"),
      api_key_param: Optional[str] = Field(
          None, description="API key for QueryParamTokenAuth"
      ),
      archivebox_url: str = Field(
          default=os.environ.get("ARCHIVEBOX_URL", None),
          description="The URL of the ArchiveBox instance",
      ),
      username: Optional[str] = Field(
          default=os.environ.get("ARCHIVEBOX_USERNAME", None),
          description="Username for authentication",
      ),
      password: Optional[str] = Field(
          default=os.environ.get("ARCHIVEBOX_PASSWORD", None),
          description="Password for authentication",
      ),
      token: Optional[str] = Field(
          default=os.environ.get("ARCHIVEBOX_TOKEN", None),
          description="Bearer token for authentication",
      ),
      api_key: Optional[str] = Field(
          default=os.environ.get("ARCHIVEBOX_API_KEY", None),
          description="API key for authentication",
      ),
      verify: Optional[bool] = Field(
          default=to_boolean(os.environ.get("ARCHIVEBOX_VERIFY", "True")),
          description="Whether to verify SSL certificates",
      ),
  ) -> dict:
      """
      Retrieve list of snapshots.
      """
      client = Api(
          url=archivebox_url,
          username=username,
          password=password,
          token=token,
          api_key=api_key,
          verify=verify,
      )
      response = client.get_snapshots(
          id=id,
          abid=abid,
          created_by_id=created_by_id,
          created_by_username=created_by_username,
          created_at__gte=created_at__gte,
          created_at__lt=created_at__lt,
          created_at=created_at,
          modified_at=modified_at,
          modified_at__gte=modified_at__gte,
          modified_at__lt=modified_at__lt,
          search=search,
          url=url,
          tag=tag,
          title=title,
          timestamp=timestamp,
          bookmarked_at__gte=bookmarked_at__gte,
          bookmarked_at__lt=bookmarked_at__lt,
          with_archiveresults=with_archiveresults,
          limit=limit,
          offset=offset,
          page=page,
          api_key=api_key_param,
      )
      return response.json()

• archivebox_api/archivebox_api.py:142-218 (helper)

  Supporting Api client method that performs the HTTP GET request to ArchiveBox API endpoint /api/v1/core/snapshots with query parameters for filtering snapshots.

  @require_auth
  def get_snapshots(
      self,
      id: Optional[str] = None,
      abid: Optional[str] = None,
      created_by_id: Optional[str] = None,
      created_by_username: Optional[str] = None,
      created_at__gte: Optional[str] = None,
      created_at__lt: Optional[str] = None,
      created_at: Optional[str] = None,
      modified_at: Optional[str] = None,
      modified_at__gte: Optional[str] = None,
      modified_at__lt: Optional[str] = None,
      search: Optional[str] = None,
      url: Optional[str] = None,
      tag: Optional[str] = None,
      title: Optional[str] = None,
      timestamp: Optional[str] = None,
      bookmarked_at__gte: Optional[str] = None,
      bookmarked_at__lt: Optional[str] = None,
      with_archiveresults: bool = False,
      limit: int = 200,
      offset: int = 0,
      page: int = 0,
      api_key: Optional[str] = None,
  ) -> requests.Response:
      """
      Retrieve list of snapshots
  
      Args:
          id: Filter by snapshot ID (startswith, icontains, timestamp__startswith).
          abid: Filter by snapshot abid (icontains).
          created_by_id: Filter by creator ID.
          created_by_username: Filter by creator username (icontains).
          created_at__gte: Filter by creation date >= (ISO 8601 format).
          created_at__lt: Filter by creation date < (ISO 8601 format).
          created_at: Filter by exact creation date (ISO 8601 format).
          modified_at: Filter by exact modification date (ISO 8601 format).
          modified_at__gte: Filter by modification date >= (ISO 8601 format).
          modified_at__lt: Filter by modification date < (ISO 8601 format).
          search: Search across url, title, tags, id, abid, timestamp (icontains).
          url: Filter by URL (exact).
          tag: Filter by tag name (exact).
          title: Filter by title (icontains).
          timestamp: Filter by timestamp (startswith).
          bookmarked_at__gte: Filter by bookmark date >= (ISO 8601 format).
          bookmarked_at__lt: Filter by bookmark date < (ISO 8601 format).
          with_archiveresults: Include archiveresults in response (default: False).
          limit: Number of results to return (default: 200).
          offset: Offset for pagination (default: 0).
          page: Page number for pagination (default: 0).
          api_key: API key for QueryParamTokenAuth (optional).
  
      Returns:
          Response: The response object from the GET request.
  
      Raises:
          ParameterError: If the provided parameters are invalid.
      """
      params = {
          k: v
          for k, v in locals().items()
          if k != "self" and v is not None and k != "api_key"
      }
      if api_key:
          params["api_key"] = api_key
      try:
          response = self._session.get(
              url=f"{self.url}/api/v1/core/snapshots",
              params=params,
              headers=self.headers,
              verify=self.verify,
          )
      except ValidationError as e:
          raise ParameterError(f"Invalid parameters: {e.errors()}")
      return response