ArchiveBox API

Instructions

Implementation Reference

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

  MCP tool handler for 'get_snapshots': decorates the function with @mcp.tool for registration, defines input schema via Pydantic Field, creates Api client, calls underlying get_snapshots helper, 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-217 (helper)

  Helper method in ArchiveBox Api class that constructs query parameters from filters and performs HTTP GET request to the ArchiveBox /api/v1/core/snapshots endpoint.
  @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