Should I Bid API

Your keyword analyses, from your own tools.

The same analysis as the app, driven by your scripts and automations: keyword ideas, quotes, launches and results, with the same credit rules and the same guardrails.

REST API · JSON · OpenAPI 3.1 · included in every paid plan

Create an API key

Getting started

First call in three steps.

One key, one header, one request.

Key — Create an API key
In Should I Bid › Integrations › Create a key. Check "Allow launching analyses" if your script must launch analyses. The key is shown only once; only its fingerprint is stored.
Header — Send it in the header
Every request carries the header Authorization: Bearer sib_live_… A key placed in the URL is refused: it would end up in logs.
Call — Make your first call
GET /api/v1/account returns your balance, your plan, your companies and their product ids.

curl -H "Authorization: Bearer $SIB_API_KEY" https://shouldibid.app/api/v1/account

Typical flow

From ideas to verdicts, in four calls.

The full Vision flow: generate ideas for a product, quote them, launch them, then read the results.

Generate ideas (free)
Up to 3 sources: company products or web pages. The response contains the new ideas, the ones already analyzed with their score, and a suggestion_batch_id valid 24 hours for a single launch.
```
POST /api/v1/suggestions
{"sources":[{"product_id":"…"}]}
```
Ask for a quote
Nothing is launched: cleaned list, credits to reserve, available balance, today's cap and any blockers.
```
POST /api/v1/analyses/estimate
{"suggestion_batch_id":"…"}
```
Launch the analysis
max_credits is required: it is the maximum amount you accept. For a Vision batch, only recommended keywords (score of 50 or more) are charged. Response 201 with the analysis id.
```
POST /api/v1/analyses
{"suggestion_batch_id":"…","max_credits":20}
```
Poll, then read the results
An analysis takes 3 to 10 minutes: poll it every 30 to 60 seconds until it is done, then read the Bid, Test or Don't bid verdicts, sorted by score.
```
GET /api/v1/analyses/{analysis_id}
```

Reference

Every route of API v1.

Base URL: https://shouldibid.app/api/v1. JSON responses, never cached, with an X-Request-Id header to give to support.

Method	Path	Purpose
GET	`/api/v1/account`	Account: plan, available credits, today's cap, companies and products.
GET	`/api/v1/analyses`	Analysis history, with filters (status, company, name) and pagination.
POST	`/api/v1/analyses`	Launches an analysis (uses credits); max_credits required.
POST	`/api/v1/analyses/estimate`	Quote without launching anything: credits to reserve, balance, cap, blockers.
GET	`/api/v1/analyses/{analysis_id}`	Progress and results of an analysis, keywords sorted by score.
POST	`/api/v1/analyses/{analysis_id}/cancel`	Stops a running analysis; keywords not analyzed yet are not charged.
GET	`/api/v1/analyses/{analysis_id}/keywords/{keyword_id}`	Detail of one keyword: score, decision, sub-scores, reasoning, advertisers.
POST	`/api/v1/suggestions`	Vision keyword ideas from 1 to 3 sources (free).
GET	`/api/v1/openapi.json`	This reference in OpenAPI 3.1 format (public, no key).

Guardrails

The same rules as the app.

Designed so that a script can never spend more than planned.

Per-key permissions

Read-only by default; launching analyses is an explicit checkbox on the key. At most 10 active keys, instant revocation.

Daily cap

At most 200 credits per 24 hours for all launches outside the app, adjustable in Integrations (0 = no launches).

One analysis at a time

Only one analysis launched through the API or Claude can run at a time; a second launch gets a 409 error.

200 keywords per launch

Beyond that, the request is refused with the list of extra keywords: nothing is silently cut.

Rate limits

120 reads and 10 writes per minute; suggestions: 5 per minute and 30 per day, per account.

Isolation

A key only sees its own account's analyses and companies; "does not exist" and "not yours" return the same 404 error.

Errors

Stable codes.

Every error carries a fixed code, an English message and the request id.

Format

{ "error": { "code": "…", "message": "…", "details": { }, "request_id": "…" } }

Code	HTTP	Meaning
`unauthorized`	401	Missing, invalid or revoked key.
`forbidden`	403	Account without a paid plan (details.reason = plan_required, with the link to the plans) or access not open yet.
`insufficient_scope`	403	Read-only key for a launch action.
`api_disabled`	503	API temporarily closed.
`not_found`	404	Resource does not exist or belongs to another account.
`method_not_allowed`	405	Method not allowed (see the Allow header).
`invalid_request`	422	Invalid parameters (details in details.issues).
`payload_too_large`	413	Request body larger than 256 KB.
`rate_limited`	429	Too many requests (see the Retry-After header).
`insufficient_credits`	402	Not enough credits.
`daily_cap_reached`	429	Daily cap reached.
`analysis_in_progress`	409	An analysis launched outside the app is already running.
`too_many_keywords`	422	More than 200 keywords in the launch.
`max_credits_exceeded`	422	The cost exceeds max_credits.
`company_required`	422	Several companies: set company_id.
`suggestion_batch_invalid`	422	Unknown, expired or already used suggestion batch.
`unavailable`	503	Service temporarily unavailable: retry.
`internal`	500	Unexpected error: give the request_id to support.

OpenAPI specification

The full machine-readable description: import it into Postman, Insomnia or a client generator.

https://shouldibid.app/api/v1/openapi.json

Connect Should I Bid to your automations.

Create an API key

Included in every paid plan · 1 credit = 1 keyword analyzed

Your keyword analyses, from your own tools.

First call in three steps.

Key — Create an API key

Header — Send it in the header

Call — Make your first call