> ## Documentation Index
> Fetch the complete documentation index at: https://docs.surfais.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Support

> How to get help with the Surfais API, and what to send so that we can find your request quickly.

## Get help

Email [support@surfais.com](mailto: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`.

<Warning>
  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.
</Warning>

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.

<CodeGroup>
  ```bash cURL theme={null}
  # -i prints the response headers, X-Request-Id among them.
  curl -sS -i "https://api.surfais.com/v1/orgs" \
    -H "Authorization: Bearer $SURFAIS_API_KEY"
  ```

  ```python Python theme={null}
  import os
  from datetime import datetime, timezone

  import requests

  response = requests.get(
      "https://api.surfais.com/v1/orgs",
      headers={"Authorization": f"Bearer {os.environ['SURFAIS_API_KEY']}"},
      timeout=30,
  )

  if not response.ok:
      try:
          code = response.json()["error"]["code"]
      except (ValueError, KeyError):
          code = None
      # Everything support needs to find the call. The API key is not part of it.
      print(
          datetime.now(timezone.utc).isoformat(),
          "GET /orgs",
          response.status_code,
          code,
          "request_id=" + str(response.headers.get("X-Request-Id")),
      )
  ```

  ```javascript Node.js theme={null}
  // request-id.mjs — run with Node 18 or later: node request-id.mjs
  const response = await fetch("https://api.surfais.com/v1/orgs", {
    headers: { Authorization: `Bearer ${process.env.SURFAIS_API_KEY}` },
  });

  if (!response.ok) {
    const body = await response.json().catch(() => ({}));
    // Everything support needs to find the call. The API key is not part of it.
    console.error(
      new Date().toISOString(),
      "GET /orgs",
      response.status,
      body.error?.code,
      `request_id=${response.headers.get("X-Request-Id")}`,
    );
  }
  ```
</CodeGroup>

## 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](/api/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](/api/webhooks/overview).

## 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](/api/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](/api/rate-limits) shows how to read yours.