Sites

Sites

toothfairyai@latest…

Manager for sites operations.

This manager provides methods to create, update, and manage sites.

Example:

>>> client = ToothFairyClient(api_key="...", workspace_id="...")
>>> site = client.sites.get(...)

Accessed via client.sites.

Methods

Method	HTTP	Endpoint
update	POST	POST /site/update
delete	DELETE	DELETE /site/delete/{site_id}
get	GET	GET /site/get/{site_id}
list	GET	GET /site/list
get_active	—	derived
get_by_status	—	derived
search	—	derived

update

Update a site.

def update(site_id: str) -> Site

Endpoint: POST /site/update · API service

Request fields

Python kwarg	Wire field	Type	Required	Description
id	id	string	yes	Unique identifier
workspace_id	workspaceid	string	no	Unique workspace identifier (UUID v4)
description	description	string	no	Detailed description of purpose and capabilities
name	name	string	no	Name of the resource
free_roaming	freeRoaming	boolean	no	Whether the crawler can roam beyond allowed paths
use_proxy	useProxy	boolean	no	Whether a proxy is used for crawling
extract_images	extractImages	boolean	no	Whether images are extracted during crawling
img_retrieval_prompt	imgRetrievalPrompt	string	no	Prompt used for image retrieval/extraction
scraping_cycle	scrapingCycle	string	no	Scraping cycle in hours: 0 (never), 24 (daily), 72 (3-day), or 168 (weekly)

Allowed: 0, 24, 72, 168 | | url | url | string | no | Public URL of the website to crawl/index | | custom_sitemap | customSitemap | string | no | Custom sitemap URL for crawling | | topics | topics | string | no | JSON-encoded list of topics associated with the chat | | metadata | metadata | string | no | Arbitrary metadata key-value pairs (JSON) | | allowed_paths | allowedPaths | string | no | List of URL paths allowed for crawling | | status | status | string | no | Current status of the resource

Allowed: active, inactive, pending, syncing, readyForValidation, inProgress | | validation_token | validationToken | string | no | Token used for domain ownership validation | | skip_owner_validation | skipOwnerValidation | boolean | no | Whether domain ownership validation is skipped | | last_validation_date | lastValidationDate | string | no | Date of the last domain validation | | last_validation_requested | lastValidationRequested | string | no | Date validation was last requested | | site_tree | siteTree | string | no | JSON-encoded site tree structure | | last_scraped | lastScraped | string | no | Date the site was last scraped | | completion_percentage | completion_percentage | string | no | Percentage of site indexing completion | | scapable_pages | scapablePages | integer | no | Number of pages that can be scraped | | scraped_pages_count | scrapedPagesCount | integer | no | Number of pages scraped | | created_by | createdBy | string | no | ID of the user who created this resource | | updated_by | updatedBy | string | no | ID of the user who last updated this resource |

Always pass snake_case keyword arguments — the Python kwarg column shows the exact name to use for each wire field (as a named parameter where it appears in the method signature, otherwise via **kwargs). The SDK converts it deterministically to the camelCase wire key the API expects. Passing camelCase directly is deprecated: it emits a warning and converts to the same wire key.

Response fields

Field	Type	Description
id	string	Unique identifier for the site
name	string	Name of the resource
description	string	Site description
url	string	Public URL of the website to crawl/index
customSitemap	string	Custom sitemap URL for crawling
workspaceID	string	Unique workspace identifier (UUID v4)
topics	object	Associated topics
status	string	Current status of the resource

Allowed: noDomain, noAnswer, active, syncing, inactive, invalidToken, failed, pending, inProgress, validationTokenCreationError, readyForValidation, tokenRequested, noSitemap | | lastValidationDate | string | Last validation timestamp | | lastValidationRequested | string | Date validation was last requested | | validationToken | string | Site validation token | | allowedPaths | array<string> | Allowed crawling paths | | siteTree | object | JSON-encoded site tree structure | | lastScraped | string | Date the site was last scraped | | skipOwnerValidation | boolean | Whether domain ownership validation is skipped | | useProxy | boolean | Whether a proxy is used for crawling | | completion_percentage | number | Site processing completion percentage | | extractImages | boolean | Whether images are extracted during crawling | | freeRoaming | boolean | Whether the crawler can roam beyond allowed paths | | scrapingCycle | integer | Scraping cycle in hours: 0 (never), 24 (daily), 72 (3-day), or 168 (weekly) | | imgRetrievalPrompt | string | Prompt used for image retrieval/extraction | | metadata | object | Arbitrary metadata key-value pairs (JSON) | | createdBy | string | ID of the user who created this resource | | updatedBy | string | ID of the user who last updated this resource | | scapablePages | integer | Number of pages that can be scraped | | scrapedPagesCount | integer | Number of pages scraped | | createdAt | string | Timestamp when this resource was created | | updatedAt | string | Timestamp when this resource was last updated |

Example

client.sites.update(site_id="agent-id")

delete

Delete a site.

def delete(site_id: str) -> Dict[str, bool]

Endpoint: DELETE /site/delete/{site_id} · API service

Response fields

Field	Type	Description
success	boolean	Operation success status
data	object	Response data
message	string	Optional success message

Example

client.sites.delete(site_id="agent-id")

get

Get a site by ID.

def get(site_id: str) -> Site

Endpoint: GET /site/get/{site_id} · API service

Response

Returns the Site object — fields documented in the update section above.

Example

client.sites.get(site_id="agent-id")

list

List all sites.

def list(
    limit: Optional[int] = None,
    offset: Optional[int] = None
) -> ListResponse

Endpoint: GET /site/list · API service

Example

client.sites.list()

get_active

Get all active sites.

def get_active() -> List[Site]

Derived method — delegates to another SDK call and performs no direct HTTP request.

Example

client.sites.get_active()

get_by_status

Get sites by status.

def get_by_status(status: str) -> List[Site]

Derived method — delegates to another SDK call and performs no direct HTTP request.

Example

client.sites.get_by_status(status="…")

search

Search sites by name.

def search(search_term: str) -> List[Site]

Derived method — delegates to another SDK call and performs no direct HTTP request.

Example

client.sites.search(search_term="…")