String docs

Authentication

Call fetch and search without a key, or authenticate Web Access, Site integrations and Composer API requests with a Bearer API key.

String Web Access API endpoints authenticate with an API key, passed as a Bearer token in the Authorization header. /v1/fetch and /v1/search also answer without one, within a daily allowance; see Without a key. Site integrations use the same key. The Composer API takes a key of its own; see Composer API.

Authorization: Bearer YOUR_API_KEY

A complete request:

curl https://request.usestring.ai/v1/fetch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com" }'

The same Bearer token authenticates the WebSocket browser endpoint — pass it as an Authorization header when connecting:

const browser = await puppeteer.connect({
  browserWSEndpoint: "wss://request.usestring.ai/v1/wss",
  headers: { Authorization: "Bearer YOUR_API_KEY" }
});

Without a key

POST /v1/fetch and POST /v1/search answer requests that carry no Authorization header, so you can try them before you have a key. Leave the header out entirely: any value in it, even an empty one, is checked as a key.

curl -i https://request.usestring.ai/v1/fetch \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://example.com" }'

The body is the same as with a key. Two headers report what is left of today's allowance (trimmed to the headers shown):

HTTP/1.1 200 OK
X-Keyless-Requests-Remaining: 49
X-Keyless-Credits-Remaining: 99

{ "statusCode": 200, "headers": { "content-type": ["text/html"] }, "data": "..." }

Without a key, a request can send only these fields. Any other field, and every other endpoint, needs a key.

EndpointFields
/v1/fetchurl, format, executeJS
/v1/searchquery, language, dateRange, sortBy, safeSearch, autocorrect, verbatim

Each IPv4 address, or IPv6 /64, can make 50 requests and spend 100 credits a day without a key. The day resets at 00:00 UTC. A fetch costs 1 credit; a fetch with executeJS: true costs 5, and so does a search. With a key, these limits don't apply: your organization's balance and rate limit do.

StatusMeaningWhat to do
400 Bad RequestA required url or query is missing or invalid, or a field needs a key.For fetch, supply a valid public HTTP(S) url; for search, a non-empty query. Remove fields that need a key, or send them with a key.
401 UnauthorizedThe request without a key wasn't accepted.Retry using an API key.
403 ForbiddenRequests without a key aren't accepted from this address.Send the request with a key.
429 Too Many RequestsA daily allowance, temporary rate limit, or capacity limit was reached.Follow Retry-After when present, or retry using a key.
503 Service UnavailableRequests without a key can't be served right now.Retry later, or send the request with a key.

A refusal may include a signupUrl, for example:

{
  "error": "Keyless limit reached",
  "message": "This address has used today's keyless allowance. It resets at 00:00 UTC, or sign up free for more: https://portal.usestring.ai/sign-up.",
  "signupUrl": "https://portal.usestring.ai/sign-up"
}

Getting a key

  1. Sign in to the String dashboard and open API Keys.
  2. Select Generate key.
  3. Copy the key from the dialog. It's shown once; after you close the dialog it can't be viewed again.

An organization can hold up to 100 active keys. Every key spends the same organization balance, so a separate key per application lets you revoke one without affecting the others.

Errors

StatusMeaningWhat to do
401 UnauthorizedA required key is missing, the header is malformed, the key is invalid or revoked, or a request without a key was not accepted.Retry with an active key in Authorization: Bearer <key>.
402 Payment RequiredThe key is valid but your organization's balance can't cover the request.Add funds under Usage & Plans, then retry.
{ "error": "Invalid API key" }

For 403 and 429, see Errors and Rate limits.

Site integrations

Send your Web Access key as a Bearer token in the Authorization header of every POST to an action.

The examples on the catalog pages read the key from an environment variable, $STRING_API_KEY. Set it once in your shell and paste the examples as they are:

export STRING_API_KEY="your key"

The GET routes that describe the integrations (the catalog and the schemas) are public and need no key. See Making a request.

How your key is used

Every request an action makes is a /v1/fetch request made with your key. Web Access checks the key, your balance, your access rules and your rate limit on each of those requests, exactly as it would for a request you sent yourself.

That has two consequences:

  • Anything your key can't do through /v1/fetch, it can't do through an integration either.
  • Each request an action makes is billed to your organization, and counts towards your rate limit. One call can make several requests; the response lists them.

When Web Access refuses the key

When Web Access refuses a request an action makes with 401, 402, 403 or 429, the whole call stops and you get Web Access's own status and body, unchanged. A 403 means your organization isn't allowed to make a request the action needs. There is no partial result, because the same refusal would apply to every remaining request.

The full list of statuses an action can return is in Responses & errors.

Composer API

Every route under /v1 on the Composer API, https://feedbuilder.usestring.ai, is authenticated with a Composer API key, sent as a Bearer token:

Authorization: Bearer sk_fb_live_…

The scheme name is matched case-insensitively (RFC 7235), so bearer works too.

Getting a Composer key

Generate one in the portal under Feeds → Composer API Keys. A key looks like:

sk_fb_live_4f2b9c1d7a3e0518_9c8d…      (public half)_(secret half)

The key is shown once and cannot be recovered

Nobody at String can read it back to you. If you lose it, revoke it and generate a new one. Keep it in your secret manager, never in source control.

The public half, everything before the last _ (sk_fb_live_4f2b9c1d7a3e0518 in the example above), is what the portal lists. It identifies the key and is safe to quote in a support request or a log line. Never share the whole key.

Composer keys are not Web Access keys

They are separate credentials against separate APIs and are not interchangeable. A Web Access key sent to the Composer API returns 401, and so does a Composer key sent to Web Access.

The tenant comes from the key, and only from the key

A key resolves to one organization, and nothing in a request can change that. A body carrying org_id, organization_id, user_id, submitted_by or any casing variant is refused with a 400 at any nesting depth — refused, not silently overwritten, so an integration cannot look multi-tenant while not being one.

The one exception is questionnaire.answers, whose object keys are Composer's own question ids rather than field names — see Gates.

What each refusal means

StatusCodeMeaning
401missing_api_keyNo Authorization header at all, or a scheme other than Bearer.
401invalid_api_keyA key was presented and not accepted. Malformed, unknown and wrong-secret are one answer.
503—The service could not check your key. Your key is fine; retry.

Malformed, unknown and secret-mismatch are one answer, so do not branch on the message. Every 401 carries WWW-Authenticate: Bearer realm="feedbuilder-api".

A 503 is always ours and always retriable — never rotate a key in response to one.

Revoking a Composer key

Revoke in the portal. Revocation takes effect at the API within 60 seconds rather than instantly — see Limits. If a key has leaked, revoke it and treat those 60 seconds as the exposure window.