Managing your API keys

Wheremore’s API lets you export Search Performance, AI Visibility, Conversion and Action Board data from systems outside the Wheremore interface.

The API is designed for server-to-server use. Every data request is authenticated with an API key and scoped to a workspace.

What you need

Before making a request, you need:

• An active Wheremore administrator account with access to the relevant workspace.
• An API key.
• The public workspace ID shown under Your Workspaces.
• Enough credits in the account’s shared credit balance.
• An optional public HTTPS callback URL if you want readiness notifications.

The API base address is:

https://app.wheremore.com/api/v2

Create an API key

1. Open API Access in Wheremore.
2. Select Generate New Key.
3. Enter a name that identifies the integration, such as Reporting server  or Production data warehouse .
4. Choose an expiry:
   • No expiry
   • 30 days
   • 90 days
   • 365 days
5. Create the key.
6. Copy and store the complete key immediately.

The complete secret is shown once. Wheremore displays only its identifying prefix afterwards.

Create separate keys for separate environments or integrations. This makes it possible to revoke one connection without interrupting the others.

Authenticate a request

Send the key in either of these headers:

X-API-Key: sk_live_your_key_here

or:

Authorization: Bearer sk_live_your_key_here

Example using the free market-discovery endpoint:

curl "https://app.wheremore.com/api/v2/markets?workspace_id=ws_your_workspace_id&domain=example.com" \
  -H "X-API-Key: sk_live_your_key_here"

Do not put an API key in a query string.

Find your workspace ID

The Your Workspaces section lists every workspace available to your account. Use Copy ID to copy the public ID, which uses the ws_...  format.

Pass it as workspace_id  on every data request:

workspace_id=ws_your_workspace_id

The public workspace ID is not the numeric workspace ID shown internally by Wheremore.

Workspace scope is enforced on every request. A key can only retrieve a website, market, project, AI configuration or conversion path when the complete resource chain belongs to the supplied workspace.

Find website and market IDs

The Your Workspaces and Markets section lists the websites and markets available through each workspace. Search Performance requests require both the website hostname and the public market ID.

You can also discover markets through the free endpoint:

curl --get "https://app.wheremore.com/api/v2/markets" \
  -H "X-API-Key: sk_live_your_key_here" \
  --data-urlencode "workspace_id=ws_your_workspace_id" \
  --data-urlencode "domain=example.com"

Use the returned market_id  in Search Performance requests. Do not substitute the internal queue ID or the market’s text name.

Credits

Creating an API v2 export is free. Pending polls and readiness notifications are also free. Credits are charged only on the first successful GET of a non-empty ready export:

Repeat GET requests for the same export ID return the saved data for free. The first paid response can include the shared account ledger balance; repeat responses return balance: null  so a historic value is not mistaken for the current balance.

How API v2 exports work

1. Create the export

Send JSON to POST /api/v2/exports/{type}  with your API key and an Idempotency-Key  header. The key must be 8 to 128 characters and may contain letters, numbers, periods, underscores, colons, slashes and hyphens. Do not put secrets or personal data in it.

POST returns an unguessable export.id , status URL and seven-day expiry. HTTP 201 means the snapshot is ready; HTTP 202 means it is pending. Creation never returns the data and never charges.

Retry the identical POST with the same idempotency key to receive the same export ID. Reusing that key with a different request returns HTTP 409.

Request JSON is strict: unknown fields are rejected, and boolean options such as include_journey  must be real JSON booleans rather than quoted strings.

2. Wait when necessary

Poll GET /api/v2/exports/{export_id}  while the job is pending. Pending polls return HTTP 202 and are free.

You may include an optional public HTTPS callback_url  in the POST body. Wheremore sends an export.ready  notification containing job metadata only. It never places exported data in the callback.

3. Retrieve the immutable result

GET the export ID using the API key. The first successful retrieval of a non-empty snapshot charges once and returns billing_status: "deducted" . Later GET requests return identical data  with already_deducted  and zero credits used.

If charging cannot complete, the job remains retrievable so the same GET can be retried after the credit issue is resolved. The saved payload expires after seven days.

Workspace access is checked again on every GET. Action Board retrieval also revalidates every project and tag represented in the saved snapshot.

Callback security requirements

Use a callback that:

• Uses https:// .
• Uses standard HTTPS port 443.
• Has a publicly resolvable hostname and public network destination.
• Does not contain a username, password or URL fragment.
• Does not depend on redirects.

Keep callback handling fast. Queue any slower processing after returning a successful response.

Rate limits

Each API key can make up to 60 requests per minute.

If the limit is exceeded, the API returns 429 Too Many Requests . Wait for the period indicated by the Retry-After  header before retrying.

Export size limit

A saved export payload can be up to 8 MiB. If a snapshot would exceed that limit, the API returns HTTP 413. Narrow the request—for example by choosing a single AI platform or phase, omitting conversion journeys, or reducing an Action Board page size—and create a new export with a new idempotency key.

Response structure

Successful data responses include:

{
  "success": true,
  "export": {
    "id": "exp_0123456789abcdef0123456789abcdef",
    "type": "serp",
    "status": "ready",
    "created_at": "2026-08-25T18:00:00Z",
    "ready_at": "2026-08-25T18:00:00Z",
    "expires_at": "2026-09-01T18:00:00Z",
    "status_url": "/api/v2/exports/exp_0123456789abcdef0123456789abcdef"
  },
  "credits_used": 0.5,
  "balance": 999.5,
  "billing_status": "deducted",
  "data": {},
  "meta": {
    "request_id": "req_example",
    "api_version": "v2",
    "data_contract": "2026-08-25",
    "duration_ms": 42
  }
}

The export  object identifies the immutable snapshot and its expiry. billing_status  is normally deducted , already_deducted  or not_charged_empty_export . Keep the request_id  when logging an integration problem. It helps support trace the exact request.

Error responses

Errors use a consistent JSON structure:

{
  "success": false,
  "error": {
    "code": 404,
    "type": "not_found",
    "message": "The requested resource was not found."
  },
  "meta": {
    "request_id": "req_example",
    "api_version": "v2",
    "data_contract": "2026-08-25"
  }
}

Common status codes:

Revoke an API key

Revoke a key when:

• An integration is retired.
• A key may have been exposed.
• A supplier or integration no longer needs access.
• You are rotating production credentials.

After revocation, requests made with that key return 401 .

Security recommendations

• Use API keys only in server-side systems.
• Store keys in a secret manager or protected environment variable.
• Never commit a key to source control.
• Never expose a key in browser JavaScript, screenshots, support tickets or analytics logs.
• Use HTTPS for all requests.
• Give each integration its own named key.
• Prefer an expiry for temporary or third-party access.
• Revoke and replace an exposed key immediately.

Troubleshooting

The API returns 401

• Confirm the complete key was copied when it was created.
• Remove accidental spaces or line breaks.
• Confirm the key has not expired or been revoked.
• Check that the header name and authentication format are correct.

The workspace is not available

• Copy the public ws_...  ID from Your Workspaces.
• Confirm the key’s user still has active access to the workspace.
• Confirm the resource has not been moved to another workspace.

The API returns 402

• Add credits to the account balance.
• Retry the same export GET afterwards.

The callback is not received

• Confirm it is a public HTTPS URL using port 443.
• Confirm the endpoint accepts POST .
• Check firewall and application logs.
• Return 2xx  quickly so Wheremore does not treat delivery as failed.
• Remember that delivery is retried, so make the callback idempotent.

A second retrieval

A second GET should return HTTP 200 with the same saved data, billing_status: "already_deducted"  and zero credits used.

Support needs to investigate

Provide:

• The response request_id .
• The endpoint and approximate UTC time.
• The workspace ID.
• The HTTP status and error type.

Do not send the complete API key.