API overview

The Suede Search API returns private, ad-free search results as JSON — the same web, image, news, video, and shopping results that power Suede, with no advertising or tracking, and no retained query history tied to you.

Base URL

One global endpoint serves every account:

https://api.suede.io

Requests are routed to the nearest infrastructure region automatically — every region serves the same API, and the optional gl parameter picks result weighting per query. There is nothing to configure.

The interactive explorer

The API host serves a live, in-browser reference. Open the root of the host (https://api.suede.io/) and it redirects to the explorer at /scalar/v1, where every endpoint is documented and callable with your own key. The machine-readable OpenAPI description is at /openapi/v1.json if you want to generate a client or import the API into another tool.

Authentication

Every request must carry your API key as a bearer token:

Authorization: Bearer suede_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Create a key in your Suede account — see Authentication. The billable search endpoints require an active Suede membership and a positive API credit balance.

A first request

curl "https://api.suede.io/v1/search?q=hello+world" \
  -H "Authorization: Bearer $SUEDE_API_KEY"

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new("Bearer", Environment.GetEnvironmentVariable("SUEDE_API_KEY"));
var json = await http.GetStringAsync("https://api.suede.io/v1/search?q=hello+world");
Console.WriteLine(json);

const res = await fetch("https://api.suede.io/v1/search?q=hello+world", {
  headers: { Authorization: `Bearer ${process.env.SUEDE_API_KEY}` },
});
console.log(await res.json());

Responses

A successful response is JSON with HTTP 200. An error uses a uniform envelope:

{ "error": { "type": "invalid_request", "message": "Query parameter 'q' is required.", "request_id": "a1b2c3d4e5f6a7b8" } }

Every response carries an X-Request-Id header (echoed as request_id in errors); quote it when contacting support. Errors lists the full set of types and status codes, and Rate limits describes throttling.

Versioning

The current version is v1, reached under the /v1 path prefix. New fields may be added to responses without a version bump, so parse defensively and ignore unknown fields. A breaking change would ship under a new version prefix.

Endpoints at a glance