Skip to main content

Get help

Email support@surfais.com. It is the same address as for the rest of Surfais, so say in the subject line that your question is about the API.

What to include

Every API response carries an X-Request-Id header. On an error, the same value is in the body as request_id. With that id we can find your exact call, so log it for every request that fails. Send us:
  • the X-Request-Id of a failing call, or the request_id from its error body;
  • the time of the call, in UTC;
  • the method and endpoint, for example PUT /orgs/{orgId}/brands/{brandId}/prompts;
  • the HTTP status and the error.code you received;
  • for a webhook question, the X-Surfais-Event-Id header of the delivery — it equals id in the event body — or the delivery’s id from GET /webhook-endpoints/{endpointId}/deliveries.
Never send your API key or a webhook signing secret: not in an email, not in a screenshot, not in a log excerpt. We will never ask for them. Remove the Authorization header from anything you paste.
A response replayed from an Idempotency-Key carries its own, new X-Request-Id. Quote the id of the response you are asking about. These samples make one call and, when it fails, print the line worth keeping in your logs.

If a key may have leaked

Treat it as urgent. Email support and ask for the key to be revoked and replaced straight away. Tell us which organisation or partner account the key belongs to — not the key itself. A revoked key stops working on its next request: every call made with it answers 401 invalid_api_key. The replacement is shown once, when it is issued, so store it in your secret manager as soon as it arrives. Authentication explains how keys work. A webhook signing secret is different, because you can replace it yourself. POST /webhook-endpoints/{endpointId}/rotate-secret replaces the secret immediately and returns the new one once. See Webhooks.

Request a key or a change of scope

Surfais issues API keys. The API has no endpoint for creating or changing a key, so ask us when you need:
  • a first key, or an extra key for another system;
  • a different scope on a key: read, or read and write;
  • for a partner, a different scope on the link to a client organisation: read_only or read_write.
The introduction explains who can get a key and what to put in the request. A key’s rate limit and monthly quota are also set per key; Rate limits and quotas shows how to read yours.