Authentication, limits and errors

Every Opttab API request carries one API key. This page covers how to send it, the rate limit, paging, and what each error means.

Authenticate

Send your key in the Authorization header as a bearer token:

curl https://api.opttab.com/v1/external/workspace \
  -H "Authorization: Bearer opt_live_xxxxxxxx"

const response = await fetch('https://api.opttab.com/v1/external/workspace', {
  headers: { Authorization: `Bearer ${process.env.OPTTAB_API_KEY}` },
});
const workspace = await response.json();

import os
import requests

response = requests.get(
    "https://api.opttab.com/v1/external/workspace",
    headers={"Authorization": f"Bearer {os.environ['OPTTAB_API_KEY']}"},
)
workspace = response.json()

These do not authenticate:

• A signed-in Opttab browser session (cookie).
• An X-API-Key header.
• An ?api_key= query parameter.

An API key also does not open any other Opttab route. It works only on /v1/external/*.

The workspace comes from the key

You choose a workspace when you create the key. Every call reads that workspace, and no route takes a workspace id. To read another workspace, create another key.

An id from another workspace behaves as if it does not exist: you get 404.

How a request is checked

Rate limit

Each key can make 60 requests per 60 seconds. The count is per key, not per IP address, so two servers sharing one key share the limit.

Request 61 inside the window gets 429 Too Many Requests with a Retry-After header:

Paging

List routes return one page at a time:

Every list response carries items, page, pageSize and totalCount. Keep asking for the next page until you have totalCount items:

curl "https://api.opttab.com/v1/external/prompts?page=2&pageSize=100" \
  -H "Authorization: Bearer opt_live_xxxxxxxx"

const headers = { Authorization: `Bearer ${process.env.OPTTAB_API_KEY}` };
const prompts = [];
for (let page = 1; ; page++) {
  const res = await fetch(
    `https://api.opttab.com/v1/external/prompts?page=${page}&pageSize=100`,
    { headers }
  );
  const body = await res.json();
  prompts.push(...body.items);
  if (body.items.length === 0 || prompts.length >= body.totalCount) break;
}

import os
import requests

headers = {"Authorization": f"Bearer {os.environ['OPTTAB_API_KEY']}"}
prompts, page = [], 1
while True:
    body = requests.get(
        "https://api.opttab.com/v1/external/prompts",
        params={"page": page, "pageSize": 100},
        headers=headers,
    ).json()
    prompts.extend(body["items"])
    if not body["items"] or len(prompts) >= body["totalCount"]:
        break
    page += 1

Paged routes: prompts, a prompt's responses, topics and competitors. GET /v1/external/responses/{responseId}/sources returns all sources in one list.

Query parameters are strict. An unknown parameter, such as ?limit=50, is refused with 400.

Error envelope

Every error has the same JSON shape:

Branch on error in your code, not on the message text.

Error reference

Example 400:

FAQ

Related