API Reference¶

This page documents the unified interface available via the ctfbridge client.

All functionality is grouped by feature and accessed through submodules of the client object.

🚀 Initializing the Client¶

`create_client(url, *, platform='auto', cache_platform=True, http=None, http_config=None)` `async` ¶

Create and return a resolved CTF client.

Parameters:

Name	Type	Description	Default
`url`	`str`	Full or base URL of the platform.	required
`platform`	`str`	Platform name or 'auto'.	`'auto'`
`cache_platform`	`bool`	Whether to cache platform detection.	`True`
`http`	`AsyncClient \| None`	Optional preconfigured HTTP client.	`None`
`http_config`	`dict[str, Any] \| None`	Configuration dictionary for the HTTP client with options: - timeout: Request timeout in seconds (int/float) - retries: Number of retries for failed requests (int) - max_connections: Maximum number of concurrent connections (int) - http2: Whether to enable HTTP/2 (bool) - auth: Authentication credentials (tuple/httpx.Auth) - event_hooks: Request/response event hooks (dict) - verify_ssl: Whether to verify SSL certificates (bool) - follow_redirects: Whether to automatically follow HTTP redirects (bool) - headers: Custom HTTP headers (dict) - proxy: Proxy configuration (dict/str) - user_agent: Custom User-Agent string (str)	`None`

Returns:

Type	Description
`CTFClient`	A resolved and ready-to-use CTFClient instance.

🔑 `client.auth`¶

Authentication service.

`login(*, username='', password='', token='')` `async` ¶

Authenticate using the platform's authentication service.

Parameters:

Name	Type	Description	Default
`username`	`str`	Username to login with.	`''`
`password`	`str`	Password to login with.	`''`
`token`	`str`	Optional authentication token.	`''`

Raises:

Type	Description
`TokenAuthError`	If token authentication fails.
`LoginError`	If username/password authentication fails.
`MissingAuthMethodError`	If no auth method is provided.
`UnauthorizedError`	If credentials are invalid.
`ServiceUnavailableError`	If auth endpoint is unavailable.

`logout()` `async` ¶

Log out of the current session.

`get_supported_auth_methods()` `async` ¶

Get supported authentication methods.

📋 `client.challenges`¶

`get_all(*, filters=None, detailed=True, enrich=True, concurrency=-1, **kwargs)` `async` ¶

Fetch all challenges.

Parameters:

Name	Type	Description	Default
`filters`	`FilterOptions \| None`	Structured filter options. If not provided, individual filter fields can be passed as keyword arguments.	`None`
`detailed`	`bool`	If True, fetch full detail for each challenge using additional requests. If False, return only the basic metadata from the listing endpoint. Note: Setting this to False improves performance on platforms where detailed challenge data requires per-challenge requests.	`True`
`enrich`	`bool`	If True, apply parsers to enrich the challenge (e.g., author, services).	`True`
`concurrency`	`int`	-1 = unlimited, 0 = sequential, N > 0 = bounded to N workers.	`-1`
`**kwargs`	`Any`	Alternative dynamic filters used only if `filters` is None.	`{}`

Returns:

Type	Description
`List[Challenge]`	List[Challenge]: A list of all challenges.

Raises:

Type	Description
`ChallengeFetchError`	If challenge listing fails.
`ChallengesUnavailableError`	If the challenges are not available
`NotAuthenticatedError`	If login is required.
`NotAuthorizedError`	If user don't have access.
`ServiceUnavailableError`	If the server is down.

`iter_all(*, filters=None, detailed=True, enrich=True, concurrency=-1, **kwargs)` `async` ¶

Stream challenges lazily instead of returning a full list.

Parameters:

Name	Type	Description	Default
`filters`	`FilterOptions \| None`	Structured filter options. If not provided, individual filter fields can be passed as keyword arguments.	`None`
`detailed`	`bool`	If True, fetch full detail for each challenge using additional requests. If False, return only the basic metadata from the listing endpoint. Note: Setting this to False improves performance on platforms where detailed challenge data requires per-challenge requests.	`True`
`enrich`	`bool`	If True, apply parsers to enrich the challenge (e.g., author, services).	`True`
`concurrency`	`int`	-1 = unlimited, 0 = sequential, N > 0 = bounded to N workers.	`-1`
`**kwargs`	`Any`	Alternative dynamic filters used only if `filters` is None.	`{}`

Yields:

Name	Type	Description
`Challenge`	`AsyncGenerator[Challenge, None]`	Each challenge that matches all filter criteria.

Raises:

Type	Description
`ChallengeFetchError`	If challenge listing fails.
`ChallengesUnavailableError`	If the challenges are not available
`NotAuthenticatedError`	If login is required.
`NotAuthorizedError`	If user don't have access.
`ServiceUnavailableError`	If the server is down.

`get_by_id(challenge_id, enrich=True)` `async` ¶

Fetch details for a specific challenge.

Parameters:

Name	Type	Description	Default
`enrich`	`bool`	If True, apply parsers to enrich the challenge (e.g., author, services).	`True`
`challenge_id`	`str`	The challenge ID.	required

Returns:

Name	Type	Description
`Challenge`	`Optional[Challenge]`	The challenge details.

Raises:

Type	Description
`ChallengeFetchError`	If challenge cannot be loaded.
`ChallengeNotFoundError`	If the challenge could not be found.
`NotAuthenticatedError`	If login is required.
`NotAuthorizedError`	If user don't have access.
`ChallengesUnavailableError`	If the challenges are not available

`submit(challenge_id, flag)` `async` ¶

Submit a flag for a challenge.

Parameters:

Name	Type	Description	Default
`challenge_id`	`str`	The challenge ID.	required
`flag`	`str`	The flag to submit.	required

Returns:

Name	Type	Description
`SubmissionResult`	`SubmissionResult`	The result of the submission.

Raises:

Type	Description
`SubmissionError`	If the submission endpoint fails or returns an invalid response.
`ChallengeNotFoundError`	If the challenge could not be found.
`NotAuthenticatedError`	If the user is not logged in.
`NotAuthorizedError`	If user don't have access.
`CTFInactiveError`	If the CTF is locked.
`RateLimitError`	If submitting too quickly.

📎 `client.attachments`:¶

Service for handling file downloads for attachments.

`download(attachment, save_dir, filename=None)` `async` ¶

Download a single attachment and save it locally.

If the attachment's URL matches the client's domain, an authenticated session is used; otherwise, a direct unauthenticated request is made.

Parameters:

Name	Type	Description	Default
`attachment`	`Attachment`	The attachment to download.	required
`save_dir`	`str`	Directory to save the downloaded file.	required
`filename`	`Optional[str]`	Optional override for the filename. If not provided, `attachment.name` is used.	`None`

Returns:

Name	Type	Description
`str`	`str`	Full path to the saved file.

Raises:

Type	Description
`AttachmentDownloadError`	If download or file saving fails.
`NotAuthenticatedError`	If authentication is required but missing.
`SessionExpiredError`	If session has expired.
`NotFoundError`	If attachment URL returns 404.
`ServiceUnavailableError`	If the platform is down or unreachable.

`download_all(attachments, save_dir)` `async` ¶

Download a list of attachments to the specified directory.

Parameters:

Name	Type	Description	Default
`attachments`	`List[Attachment]`	List of attachments to download.	required
`save_dir`	`str`	Directory to save the downloaded files.	required

Returns:

Type	Description
`List[str]`	List[str]: List of full paths to the downloaded files.

Raises:

Type	Description
`AttachmentDownloadError`	If download or file saving fails.
`NotAuthenticatedError`	If authentication is required but missing.
`SessionExpiredError`	If session has expired.
`NotFoundError`	If attachment URL returns 404.
`ServiceUnavailableError`	If the platform is down or unreachable.

🏆 `client.scoreboard`:¶

Class for accessing scoreboard data.

`get_top(limit=0)` `async` ¶

Return the top scoreboard entries.

Parameters:

Name	Type	Description	Default
`limit`	`int`	Maximum number of entries to return. If 0, return all entries.	`0`

Returns:

Type	Description
`List[ScoreboardEntry]`	List[ScoreboardEntry]: A list of scoreboard entries sorted by rank or score.

Raises:

Type	Description
`ScoreboardFetchError`	If scoreboard cannot be retrieved.
`CTFInactiveError`	If scoreboard is locked.
`ServiceUnavailableError`	If platform is down.

🌐 `client.session`¶

HTTP session management.

`set_token(token)` `async` ¶

Set a bearer token in the session headers.

Parameters:

Name	Type	Description	Default
`token`	`str`	The bearer token to use for authentication.	required

`set_headers(headers)` `async` ¶

Update session headers with custom key-value pairs.

Parameters:

Name	Type	Description	Default
`headers`	`Dict[str, str]`	A dictionary of headers to add or update.	required

`set_cookie(name, value, domain=None)` `async` ¶

Set a cookie in the session.

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the cookie.	required
`value`	`str`	Value of the cookie.	required
`domain`	`str \| None`	The domain for which the cookie is valid.	`None`

`save(path)` `async` ¶

Save the session's current state, including cookies and headers, to a file.

Parameters:

Name	Type	Description	Default
`path`	`str`	Path to the file where session state should be saved.	required

Raises:

Type	Description
`SessionError`	If saving the session fails (e.g., due to file I/O issues).

`load(path)` `async` ¶

Load the session state (cookies and headers) from a file.

Parameters:

Name	Type	Description	Default
`path`	`str`	Path to the file from which to load the session state.	required

Raises:

Type	Description
`SessionError`	If loading the session fails (e.g., file not found or corrupt).

✨ `client.capabilities`¶

The capabilities property provides a synchronous way to check which features are supported by the current platform client. It returns a Capabilities object.

Represents the features supported by a ctfbridge platform client.

Fields:

login (bool)
session_persistence (bool)
view_team_information (bool)
view_user_profile (bool)
view_ctf_details (bool)
view_announcements (bool)
view_scoreboard (bool)
view_challenges (bool)
submit_flags (bool)
download_attachments (bool)
manage_challenge_instances (bool)

`login = False` `pydantic-field` ¶

Indicates if the client supports authentication.

`session_persistence = True` `pydantic-field` ¶

Indicates if the session (cookies/tokens) can be reliably saved and loaded.

`view_team_information = False` `pydantic-field` ¶

Indicates if the client can fetch details about a team, such as its members and rank.

`view_user_profile = False` `pydantic-field` ¶

Indicates if the client can fetch details for the authenticated user's profile.

`view_ctf_details = False` `pydantic-field` ¶

Indicates if the client can fetch metadata about the CTF event itself (e.g., start/end times, rules).

`view_announcements = False` `pydantic-field` ¶

Indicates if the client can fetch broadcast announcements for the CTF.

`view_scoreboard = False` `pydantic-field` ¶

Indicates if the client supports viewing the scoreboard.

`view_challenges = False` `pydantic-field` ¶

Indicates if the client supports listing challenges.

`submit_flags = False` `pydantic-field` ¶

Indicates if the client supports submitting flags.

`download_attachments = True` `pydantic-field` ¶

Indicates if the client can download challenge attachments.

`manage_challenge_instances = False` `pydantic-field` ¶

Indicates if the client can start, stop, or get connection info for on-demand challenge instances (e.g., Docker containers).

API Reference¶

🚀 Initializing the Client¶

create_client(url, *, platform='auto', cache_platform=True, http=None, http_config=None) async ¶

🔑 client.auth¶

login(*, username='', password='', token='') async ¶

logout() async ¶

get_supported_auth_methods() async ¶

📋 client.challenges¶

get_all(*, filters=None, detailed=True, enrich=True, concurrency=-1, **kwargs) async ¶

iter_all(*, filters=None, detailed=True, enrich=True, concurrency=-1, **kwargs) async ¶

get_by_id(challenge_id, enrich=True) async ¶

submit(challenge_id, flag) async ¶

📎 client.attachments:¶

download(attachment, save_dir, filename=None) async ¶

download_all(attachments, save_dir) async ¶

🏆 client.scoreboard:¶

get_top(limit=0) async ¶

🌐 client.session¶

set_token(token) async ¶

set_headers(headers) async ¶

set_cookie(name, value, domain=None) async ¶

save(path) async ¶

load(path) async ¶

✨ client.capabilities¶

login = False pydantic-field ¶

session_persistence = True pydantic-field ¶

view_team_information = False pydantic-field ¶

view_user_profile = False pydantic-field ¶

view_ctf_details = False pydantic-field ¶

view_announcements = False pydantic-field ¶

view_scoreboard = False pydantic-field ¶

view_challenges = False pydantic-field ¶

submit_flags = False pydantic-field ¶

download_attachments = True pydantic-field ¶

manage_challenge_instances = False pydantic-field ¶

`create_client(url, *, platform='auto', cache_platform=True, http=None, http_config=None)` `async` ¶

🔑 `client.auth`¶

`login(*, username='', password='', token='')` `async` ¶

`logout()` `async` ¶

`get_supported_auth_methods()` `async` ¶

📋 `client.challenges`¶

`get_all(*, filters=None, detailed=True, enrich=True, concurrency=-1, **kwargs)` `async` ¶

`iter_all(*, filters=None, detailed=True, enrich=True, concurrency=-1, **kwargs)` `async` ¶

`get_by_id(challenge_id, enrich=True)` `async` ¶

`submit(challenge_id, flag)` `async` ¶

📎 `client.attachments`:¶

`download(attachment, save_dir, filename=None)` `async` ¶

`download_all(attachments, save_dir)` `async` ¶

🏆 `client.scoreboard`:¶

`get_top(limit=0)` `async` ¶

🌐 `client.session`¶

`set_token(token)` `async` ¶

`set_headers(headers)` `async` ¶

`set_cookie(name, value, domain=None)` `async` ¶

`save(path)` `async` ¶

`load(path)` `async` ¶

✨ `client.capabilities`¶

`login = False` `pydantic-field` ¶

`session_persistence = True` `pydantic-field` ¶

`view_team_information = False` `pydantic-field` ¶

`view_user_profile = False` `pydantic-field` ¶

`view_ctf_details = False` `pydantic-field` ¶

`view_announcements = False` `pydantic-field` ¶

`view_scoreboard = False` `pydantic-field` ¶

`view_challenges = False` `pydantic-field` ¶

`submit_flags = False` `pydantic-field` ¶

`download_attachments = True` `pydantic-field` ¶

`manage_challenge_instances = False` `pydantic-field` ¶