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, tracking, or query logging.

Base URL

One global endpoint serves every account:

https://api.suede.io

Requests are routed to the nearest infrastructure region automatically, and your account's home region is applied server-side — it affects only the default result weighting. 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