Integrations and crawlers

Read GET /projects/{projectId}/integrations for connection metadata and generations. API connection reads do not return provider access or refresh tokens.

The setup endpoint supports google_analytics, google_search_console, and webflow. It requires read + integrations and returns the project context, a browser URL, and instructions.

OAuth requires an interactive owner session and provider consent. Open the requested project in the browser, then its Integrations tab. The setup endpoint does not change the browser's selected project or complete consent with an API key.

Use the authorized provider-resource endpoints to list GA4 properties, Search Console sites, or Webflow sites and collections. Resource inspection requires read + integrations.

Configure the returned connection ID with write + integrations. Google configuration selects a GA4 property or Search Console site and queues its existing backfill. Webflow configuration validates the site, collection, and required field mapping.

Connection and provider IDs are different identifiers. Use Searchly's UUID connection ID in the connection path; provider resource IDs follow their own schemas. A successful configuration request is not proof that a provider sync has completed.

Create a crawler source with POST /projects/{projectId}/crawler-sources and an empty JSON body. The response reveals its source token once and lists its intake URLs in endpoints: api, vercel, and cloudflare. Store that credential separately from your Searchly API key. A sender uses it as the bearer token for any of those URLs. To connect a platform, follow Set up crawler requests; a custom sender posts the format under Send events from your own code.

Read crawler source state under /agent-analytics/crawler-sources. Rotation uses PATCH /crawler-sources/{connectionId} with action: rotate and the current expectedGeneration. Replace the installed source token with the newly returned one. The replaced token keeps working until the returned previousValidUntil, 24 hours after the rotation; rotating again before then stops that earlier token at once. Revocation uses the dedicated crawler DELETE endpoint and stops every token of the source immediately.

Recorded crawler events and Page Records retain source and coverage information. Read reports and evidence before interpreting missing events or page measurements.

Provider disconnect requires write + integrations. A Webflow disconnect must include the connection's current generation in If-Match, for example If-Match: "3". If the connection changes, refresh its metadata before retrying.

Disconnect retains the native authorization and delivery safeguards. Use the dedicated crawler endpoint for crawler sources, and review provider delivery state before changing a publishing destination.