REST API reference

Base URL: https://freshlycited.com/api/v1. Authenticate with an API key: Authorization: Bearer ipk_… (or X-Api-Key). Every response is { "ok": true, "data": … } or { "ok": false, "error": { "code", "message", "request_id" } } and carries an X-Request-Id header. This page is generated from the same OpenAPI 3.1 spec the server publishes, which is built from the live route table.

The story · 3 steps

Get an API keyFree plan: 10 free links to try (once you verify your email), then 100 free checks a month, no card.

bash

curl https://freshlycited.com/api/v1/me -H "Authorization: Bearer ipk_YOUR_KEY"

Errors: 401 missing/invalid key · 402 not enough credits · 403 role too low or account awaiting approval · 404 not found or outside your workspace · 409 conflict · 413 more than 10,000 URLs · 422 validation · 429 rate limit (see Retry-After). Lists take page, page_size (≤200), sort, dir and return { items, total, page, page_size }.

Account

Identity, profile, sessions and connected apps.

GET `/me`

Identity of the API key or session.

GET `/mcp-tools`

MCP tool catalog (names, descriptions, input schemas, examples).

GET `/routes`

Every REST route.

GET `/pricing`

Credits, packs, plans, the credit-back guarantee and rate limits (USD).

GET `/oauth/grants`

Apps connected to your login via OAuth.

DELETE `/oauth/grants/{id}`

Disconnect an app (revokes its tokens).

Parameter	In	Type	Required	Description
`id`	path	string	yes

GET `/profile`

Your profile.

PATCH `/profile`

Update your profile.

Request body (JSON):

Any JSON object (see the app for fields).

DELETE `/profile`

Delete your account.

Request body (JSON):

Any JSON object (see the app for fields).

POST `/profile/password`

Change your password.

Request body (JSON):

Parameter	Type	Required	Description
`current_password`	string	yes
`new_password`	string	yes

GET `/profile/sessions`

Your sign-in sessions.

DELETE `/profile/sessions/{sid}`

Sign out one session.

Parameter	In	Type	Required	Description
`sid`	path	string	yes

Clients

Your agency workspace, client workspaces and members.

GET `/tenants`

List your workspace and its clients (tree order). MCP tool: list_tenants.

Parameter	In	Type	Required
`q`	query	string	no
`kind`	query	`agency` \| `team` \| `client`	no
`include_archived`	query	string	no

POST `/tenants`

Create a client or team workspace. Role admin or higher. MCP tool: create_sub_tenant.

Request body (JSON):

Parameter	Type	Required	Description
`name`	string (≤120 chars)	yes
`kind`	`team` \| `client`	no
`parent_id`	string	no	Workspace (tenant) id. Defaults to the workspace of the key or connection; use list_tenants to find client ids.
`notes`	string	no

GET `/tenants/{id}`

Get a workspace. MCP tool: get_tenant.

Parameter	In	Type	Required	Description
`id`	path	string	yes

PATCH `/tenants/{id}`

Update, move, archive or restore a workspace. Role admin or higher. MCP tool: update_tenant.

Parameter	In	Type	Required	Description
`id`	path	string	yes

Request body (JSON):

Parameter	Type	Required
`name`	string	no
`kind`	`team` \| `client`	no
`notes`	string	no
`default_recheck_days`	integer (≥0, ≤5)	no
`parent_id`	string	no
`archived`	boolean	no

DELETE `/tenants/{id}`

Delete an empty workspace (confirm=<name>) or archive it (mode=archive). Role admin or higher. MCP tool: delete_tenant.

Parameter	In	Type	Required
`id`	path	string	yes
`confirm`	query	string	no
`mode`	query	`delete` \| `archive`	no

GET `/tenants/{id}/members`

List a workspace's members. MCP tool: list_members.

Parameter	In	Type	Required	Description
`id`	path	string	yes

POST `/tenants/{id}/members`

Add or invite a member. Role admin or higher. MCP tool: add_member.

Parameter	In	Type	Required	Description
`id`	path	string	yes

Request body (JSON):

Parameter	Type	Required
`email`	string	yes
`role`	`owner` \| `admin` \| `member` \| `client_viewer`	yes
`name`	string	no

PATCH `/tenants/{id}/members/{uid}`

Change a member's role. Role admin or higher. MCP tool: update_member_role.

Parameter	In	Type	Required	Description
`id`	path	string	yes
`uid`	path	string	yes

Request body (JSON):

Parameter	Type	Required	Description
`role`	`owner` \| `admin` \| `member` \| `client_viewer`	yes

DELETE `/tenants/{id}/members/{uid}`

Remove a member. Role admin or higher. MCP tool: remove_member.

Parameter	In	Type	Required	Description
`id`	path	string	yes
`uid`	path	string	yes

GET `/members`

List members (of tenant_id, default yours).

Parameter	In	Type	Required	Description
`tenant_id`	query	string	no	Limit to one workspace

POST `/members`

Add or invite a member. Role admin or higher.

Request body (JSON):

Parameter	Type	Required	Description
`email`	string	yes
`tenant_id`	string	no	Workspace (tenant) id. Defaults to the workspace of the key or connection; use list_tenants to find client ids.
`role`	`owner` \| `admin` \| `member` \| `client_viewer`	yes
`name`	string	no

GET `/tenants/{id}/branding`

White-label branding of a workspace and what the plan allows.

Parameter	In	Type	Required	Description
`id`	path	string	yes

PUT `/tenants/{id}/branding`

Update white-label branding (logo: Agency Starter+; colours, sender name: Agency Pro+; custom domain: Agency Scale). Role admin or higher.

Parameter	In	Type	Required	Description
`id`	path	string	yes

Request body (JSON):

Parameter	Type	Required
`logo_url`	string \| null	no
`accent`	string \| null	no
`from_name`	string \| null	no
`domain`	string \| null	no

Settings

Workspace and platform settings.

GET `/settings/email`

Email delivery settings. Platform admin only.

PUT `/settings/email`

Update email delivery settings. Platform admin only.

Request body (JSON):

Any JSON object (see the app for fields).

POST `/settings/email/test`

Send a test email. Platform admin only.

Request body (JSON):

Parameter	Type	Required	Description
`to`	string	no

GET `/settings/email/templates`

Email templates. Role admin or higher.

GET `/settings/email/templates/{name}`

Preview an email template. Role admin or higher.

Parameter	In	Type	Required	Description
`name`	path	string	yes

POST `/settings/email/templates/{name}/send`

Send a template preview to yourself. Role admin or higher.

Parameter	In	Type	Required	Description
`name`	path	string	yes

Request body (JSON):

Parameter	Type	Required	Description
`to`	string	no

GET `/emails`

Email log. Role admin or higher.

Parameter	In	Type	Required
`page`	query	string	no
`page_size`	query	string	no
`q`	query	string	no
`sort`	query	string	no
`dir`	query	`asc` \| `desc`	no
`status`	query	string	no
`template`	query	string	no

GET `/emails/{id}`

One logged email. Role admin or higher.

Parameter	In	Type	Required	Description
`id`	path	string	yes

POST `/emails/{id}/resend`

Resend a logged email. Role admin or higher.

Parameter	In	Type	Required	Description
`id`	path	string	yes

GET `/tenants/{id}/notifications`

Notification settings of a workspace.

Parameter	In	Type	Required	Description
`id`	path	string	yes

PATCH `/tenants/{id}/notifications`

Update notification settings. Role admin or higher.

Parameter	In	Type	Required	Description
`id`	path	string	yes

Request body (JSON):

Any JSON object (see the app for fields).

POST `/tenants/{id}/digest`

Send the daily digest now. Role admin or higher.

Parameter	In	Type	Required	Description
`id`	path	string	yes

Request body (JSON):

Parameter	Type	Required	Description
`to`	string	no
`skip_if_unchanged`	boolean	no

GET `/tenants/{id}/digest/preview`

Preview the daily digest.

Parameter	In	Type	Required	Description
`id`	path	string	yes

GET `/settings/integrations`

Check engines, caps and spend. Platform admin only.

PUT `/settings/integrations`

Update check engines and caps. Platform admin only.

Request body (JSON):

Any JSON object (see the app for fields).

POST `/settings/integrations/{source}/test`

Test a check engine. Platform admin only.

Parameter	In	Type	Required	Description
`source`	path	string	yes

GET `/settings/crawl`

Crawl routes: status, circuit breaker, last errors, plan and allowance. Platform admin only.

PUT `/settings/crawl`

Update crawl plan tier, cost, monthly allowance and failover thresholds. Platform admin only.

Request body (JSON):

Parameter	Type	Required
`plan_tier`	string \| null	no
`cost_per_indexed_usd`	number \| null	no
`monthly_allowance`	integer (≥-9007199254740991, ≤9007199254740991) \| null	no
`fallback_cost_per_indexed_usd`	number	no
`failover_errors`	integer (≥-9007199254740991, ≤9007199254740991)	no
`failover_window_min`	integer (≥-9007199254740991, ≤9007199254740991)	no
`failover_cooldown_min`	integer (≥-9007199254740991, ≤9007199254740991)	no
`failover_allowance_pct`	number	no
`failover_day3_min_rate_pct`	number	no

POST `/settings/crawl/breaker/reset`

Close the crawl circuit breaker (route new batches to the primary again). Platform admin only.

POST `/settings/crawl/{route}/test`

Test a crawl route (free, read-only call). Platform admin only.

Parameter	In	Type	Required	Description
`route`	path	string	yes

GET `/settings/job-sync`

Crawl-status sync schedule.

PUT `/settings/job-sync`

Update the crawl-status sync schedule. Platform admin only.

Request body (JSON):

Parameter	Type	Required
`frequency`	`daily` \| `6h` \| `1h`	no
`time`	string	no
`tz`	string	no

GET `/settings/access`

Sign-up mode and the Free plan grant. Platform admin only.

PUT `/settings/access`

Update the sign-up mode. Platform admin only.

Request body (JSON):

Parameter	Type	Required	Description
`signup_mode`	`approval` \| `open`	no

Credits

Balances, ledger, allocations and credit packs.

GET `/credits`

Credit balance and recent ledger. MCP tool: get_credits.

Parameter	In	Type	Required	Description
`tenant_id`	query	string	no	Limit to one workspace

GET `/credits/ledger`

Paginated credit ledger (kind=index|check). MCP tool: list_ledger.

Parameter	In	Type	Required	Description
`page`	query	string	no
`page_size`	query	string	no
`q`	query	string	no
`sort`	query	string	no
`dir`	query	`asc` \| `desc`	no
`tenant_id`	query	string	no	Limit to one workspace
`kind`	query	`index` \| `check`	no
`direction`	query	`in` \| `out`	no

GET `/credits/ledger/{id}`

One ledger entry with related lines.

Parameter	In	Type	Required	Description
`id`	path	string	yes

POST `/credits/ledger/{id}/reverse`

Reverse an allocation or grant. Role admin or higher. MCP tool: reverse_ledger_entry.

Parameter	In	Type	Required	Description
`id`	path	string	yes

POST `/credits/allocate`

Give index or check credits to a client (negative pulls back). Role admin or higher. MCP tool: allocate_credits.

Request body (JSON):

Parameter	Type	Required	Description
`tenant_id`	string	yes
`amount`	integer (≥-9007199254740991, ≤9007199254740991)	yes
`kind`	`index` \| `check`	no	Which credits to move (default index)
`note`	string	no

POST `/credits/adjust`

Adjust index or check credits (platform admin). Platform admin only.

Request body (JSON):

Parameter	Type	Required
`tenant_id`	string	yes
`amount`	integer (≥-9007199254740991, ≤9007199254740991)	yes
`reason`	string	yes
`kind`	`index` \| `check`	no

GET `/credits/packs`

Credit packs (index + check credits, USD).

GET `/credits/requests`

Credit pack requests.

Parameter	In	Type	Required	Description
`status`	query	string	no

POST `/credits/requests`

Request a credit pack. Role admin or higher.

Request body (JSON):

Parameter	Type	Required
`pack`	`try` \| `boost` \| `pro` \| `checks` \| `checks_l`	yes
`tenant_id`	string	no
`note`	string	no

GET `/plans`

Plans and their limits (USD).

Pushes

Push links to Google (index jobs) and track them. Verified IndexNow hosts are also sent to Bing & co.

GET `/jobs`

List pushes and visibility checks, each with an outcome. MCP tool: list_jobs.

Parameter	In	Type	Required	Description
`page`	query	string	no
`page_size`	query	string	no
`q`	query	string	no
`sort`	query	string	no
`dir`	query	`asc` \| `desc`	no
`tenant_id`	query	string	no	Limit to one workspace
`status`	query	string	no
`type`	query	`index` \| `check`	no

POST `/jobs`

Push links (index job): free pre-flight, 1 index credit reserved per link and used only if indexed (credit back after the last re-check); verified IndexNow hosts are also sent to Bing. Role member or higher. MCP tool: submit_index_job.

Request body (JSON):

Parameter	Type	Required	Description
`urls`	array of string	yes	Full http(s) URLs, up to 10,000 (Free plan: 50). Duplicates and invalid entries are dropped and reported.
`mode`	`standard`	no	Lane. Only standard exists: 1 index credit per link, used only if the link gets indexed (credit back after 7 days if not). A faster priority lane is not available yet.
`tenant_id`	string	no	Workspace (tenant) id. Defaults to the workspace of the key or connection; use list_tenants to find client ids.
`name`	string (≤200 chars)	no	Label shown in lists, emails and client reports
`drip_days`	integer (≥0, ≤30)	no	Spread the push over this many days (0 = all now)
`recheck_days`	integer (≥0, ≤5)	no	Deprecated, kept for compatibility: re-checks now follow the guarantee schedule (day 1, 3, 7) automatically
`pre_check`	boolean	no	Take a 'before' snapshot first (1 check credit/URL); every link is still pushed
`smart`	boolean	no	Recommended: check first and only push what Google can't see (their index credit comes back)
`preflight`	boolean	no	Run the free pre-flight (default true)
`skip_flagged`	boolean	no	Skip URLs the pre-flight flags, for free (default true)
`push_anyway`	boolean \| array of string	no	Push flagged URLs anyway (true = all, or a list). They aren't covered by the guarantee: their index credit is used
`force_refresh`	boolean	no	Refresh anyway (needs smart=true): links Google already has are sent too and use 1 index credit each when sent. No credit back: we can't see when Google re-crawls a page it already has, so the guarantee doesn't apply. IndexNow pings stay free
`indexnow_force`	boolean	no	Resend to IndexNow even if sent in the last 24 h (only when the content changed again)

POST `/urls/validate`

Validate and de-duplicate URLs (free). MCP tool: validate_urls.

Request body (JSON):

Parameter	Type	Required	Description
`urls`	array of string \| string	yes

POST `/preflight`

Pre-flight URLs before pushing (free): 4xx/5xx, noindex, robots.txt, redirects, canonical elsewhere. Role member or higher. MCP tool: preflight_urls.

Request body (JSON):

Parameter	Type	Required	Description
`urls`	array of string	yes
`tenant_id`	string	no	Workspace (tenant) id. Defaults to the workspace of the key or connection; use list_tenants to find client ids.

GET `/jobs/{id}`

One push or check with outcome, comparison and IndexNow summary. MCP tool: get_job_status.

Parameter	In	Type	Required	Description
`id`	path	string	yes
`url_limit`	query	string	no

PATCH `/jobs/{id}`

Rename a job. Role member or higher. MCP tool: update_job.

Parameter	In	Type	Required	Description
`id`	path	string	yes

Request body (JSON):

Parameter	Type	Required	Description
`name`	string (≤200 chars)	no
`recheck_days`	integer (≥0, ≤5)	no

DELETE `/jobs/{id}`

Delete a finished job. Role admin or higher. MCP tool: delete_job.

Parameter	In	Type	Required	Description
`id`	path	string	yes

POST `/jobs/{id}/sync`

Refresh crawl status now.

Parameter	In	Type	Required	Description
`id`	path	string	yes

POST `/jobs/{id}/cancel`

Cancel a job (unsent links refunded). Role member or higher. MCP tool: cancel_job.

Parameter	In	Type	Required	Description
`id`	path	string	yes

POST `/jobs/{id}/retry`

Push failed links again. Role member or higher. MCP tool: retry_job.

Parameter	In	Type	Required	Description
`id`	path	string	yes

Request body (JSON):

Parameter	Type	Required	Description
`mode`	`standard`	no	Lane. Only standard exists: 1 index credit per link, used only if the link gets indexed (credit back after 7 days if not). A faster priority lane is not available yet.

POST `/jobs/{id}/send-unindexed`

Push the links Google can't see again. Role member or higher. MCP tool: send_unindexed_to_indexer.

Parameter	In	Type	Required	Description
`id`	path	string	yes

Request body (JSON):

Parameter	Type	Required	Description
`mode`	`standard`	no	Lane. Only standard exists: 1 index credit per link, used only if the link gets indexed (credit back after 7 days if not). A faster priority lane is not available yet.
`drip_days`	integer (≥0, ≤30)	no
`recheck_days`	integer (≥0, ≤5)	no	Deprecated: guarantee re-checks are automatic

GET `/jobs/{id}/urls`

Parameter	In	Type	Required
`id`	path	string	yes
`page`	query	string	no
`page_size`	query	string	no
`q`	query	string	no
`sort`	query	string	no
`dir`	query	`asc` \| `desc`	no
`state`	query	string	no
`indexed`	query	`yes` \| `no` \| `unknown`	no
`credit`	query	`reserved` \| `consumed` \| `released` \| `excluded`	no

DELETE `/jobs/{id}/urls/{uid}`

Remove one link from a finished job. Role member or higher. MCP tool: delete_job_url.

Parameter	In	Type	Required	Description
`id`	path	string	yes
`uid`	path	string	yes

Checks

Visibility checks (index checks), stored search results, CSV exports and client reports.

POST `/jobs/{id}/check`

Re-check a job's links now (1 check credit per link, 5 with scan_live). Role member or higher.

Parameter	In	Type	Required	Description
`id`	path	string	yes

Request body (JSON):

Parameter	Type	Required	Description
`url_ids`	array of integer (≥-9007199254740991, ≤9007199254740991)	no
`engine`	`scan_standard` \| `scan_live` \| `scan_bing` \| `upstream`	no

GET `/jobs/{id}/google`

Stored search results (pass url for one link's history). MCP tool: get_check_results.

Parameter	In	Type	Required	Description
`id`	path	string	yes
`url`	query	string	no

GET `/jobs/{id}/google/raw/{rid}`

Raw stored search response.

Parameter	In	Type	Required	Description
`id`	path	string	yes
`rid`	path	string	yes

GET `/jobs/{id}/csv`

Export a job as CSV. MCP tool: export_job_csv.

Parameter	In	Type	Required	Description
`id`	path	string	yes

POST `/check`

Visibility check (index check). Role member or higher. MCP tool: check_index.

Request body (JSON):

Parameter	Type	Required	Description
`urls`	array of string	no
`job_id`	string	no
`tenant_id`	string	no	Workspace (tenant) id. Defaults to the workspace of the key or connection; use list_tenants to find client ids.
`name`	string (≤200 chars)	no
`engine`	`scan_standard` \| `scan_live` \| `scan_bing` \| `upstream`	no

POST `/jobs/{id}/share`

Create (or return) a client report link. Role member or higher. MCP tool: share_job_report.

Parameter	In	Type	Required	Description
`id`	path	string	yes

DELETE `/jobs/{id}/share`

Stop sharing a client report. Role member or higher.

Parameter	In	Type	Required	Description
`id`	path	string	yes

IndexNow

Sites verified for IndexNow (Bing, Copilot, Yandex, Seznam, Naver, Yep) and what each push sent.

GET `/jobs/{id}/indexnow`

What a push sent to IndexNow (per link + summary). MCP tool: get_job_indexnow.

Parameter	In	Type	Required	Description
`id`	path	string	yes

GET `/indexnow/sites`

List IndexNow sites. MCP tool: list_indexnow_sites.

Parameter	In	Type	Required	Description
`tenant_id`	query	string	no	Limit to one workspace

POST `/indexnow/sites`

Add a site (returns the key to host). Role admin or higher. MCP tool: add_indexnow_site.

Request body (JSON):

Parameter	Type	Required	Description
`host`	string	yes	Domain or any URL on it, e.g. https://www.example.com/blog
`tenant_id`	string	no	Workspace (tenant) id. Defaults to the workspace of the key or connection; use list_tenants to find client ids.
`key_location`	string	no	Optional full URL of the key file on the same host, e.g. https://example.com/keys/indexnow.txt

GET `/indexnow/sites/{id}`

One IndexNow site with recent submissions.

Parameter	In	Type	Required	Description
`id`	path	string	yes

PATCH `/indexnow/sites/{id}`

Turn pings on/off or change the key location. Role admin or higher. MCP tool: update_indexnow_site.

Parameter	In	Type	Required	Description
`id`	path	string	yes

Request body (JSON):

Parameter	Type	Required	Description
`enabled`	boolean	no
`key_location`	string \| null	no

DELETE `/indexnow/sites/{id}`

Remove an IndexNow site. Role admin or higher. MCP tool: delete_indexnow_site.

Parameter	In	Type	Required	Description
`id`	path	string	yes

POST `/indexnow/sites/{id}/verify`

Fetch the key file and verify the site. Role member or higher. MCP tool: verify_indexnow_site.

Parameter	In	Type	Required	Description
`id`	path	string	yes

POST `/indexnow/sites/{id}/rotate-key`

Generate a new key (verify again afterwards). Role admin or higher.

Parameter	In	Type	Required	Description
`id`	path	string	yes

POST `/indexnow/preview`

How many of these URLs would also go to IndexNow.

Request body (JSON):

Parameter	Type	Required	Description
`urls`	array of string	yes
`tenant_id`	string	no

GET `/indexnow/own`

Our own site's IndexNow submissions (platform admin). Platform admin only.

POST `/indexnow/tick`

Run the daily re-verification now (platform admin). Platform admin only.

API keys

API keys and their per-key limits.

GET `/api-keys`

List API keys (prefix only). MCP tool: list_api_keys.

Parameter	In	Type	Required	Description
`tenant_id`	query	string	no	Limit to one workspace
`status`	query	`active` \| `revoked`	no
`q`	query	string	no

POST `/api-keys`

Create an API key (secret shown once). Role admin or higher. MCP tool: create_api_key.

Request body (JSON):

Parameter	Type	Required	Description
`name`	string	no
`tenant_id`	string	no	Workspace (tenant) id. Defaults to the workspace of the key or connection; use list_tenants to find client ids.
`role`	`owner` \| `admin` \| `member` \| `client_viewer`	no
`rate_per_min`	integer (≥1, ≤600)	no
`rate_per_day`	integer (≥1, ≤100000)	no
`daily_credit_cap`	integer (≥1, ≤9007199254740991) \| null	no

GET `/api-keys/{id}`

One API key.

Parameter	In	Type	Required	Description
`id`	path	string	yes

PATCH `/api-keys/{id}`

Rename, change role or limits. Role admin or higher. MCP tool: update_api_key.

Parameter	In	Type	Required	Description
`id`	path	string	yes

Request body (JSON):

Parameter	Type	Required
`name`	string	no
`role`	`owner` \| `admin` \| `member` \| `client_viewer`	no
`rate_per_min`	integer (≥1, ≤600) \| null	no
`rate_per_day`	integer (≥1, ≤100000) \| null	no
`daily_credit_cap`	integer (≥1, ≤9007199254740991) \| null	no

DELETE `/api-keys/{id}`

Delete an API key. Role admin or higher. MCP tool: delete_api_key.

Parameter	In	Type	Required	Description
`id`	path	string	yes

POST `/api-keys/{id}/revoke`

Revoke an API key. Role admin or higher. MCP tool: revoke_api_key.

Parameter	In	Type	Required	Description
`id`	path	string	yes

Platform

FreshlyCited platform administration.

GET `/users`

List users. Platform admin only. MCP tool: list_users.

Parameter	In	Type	Required
`page`	query	string	no
`page_size`	query	string	no
`q`	query	string	no
`sort`	query	string	no
`dir`	query	`asc` \| `desc`	no
`status`	query	string	no

POST `/users`

Create a user. Platform admin only.

Request body (JSON):

Any JSON object (see the app for fields).

GET `/users/{id}`

One user. Platform admin only. MCP tool: get_user.

Parameter	In	Type	Required	Description
`id`	path	string	yes

PATCH `/users/{id}`

Update a user. Platform admin only.

Parameter	In	Type	Required	Description
`id`	path	string	yes

Request body (JSON):

Any JSON object (see the app for fields).

DELETE `/users/{id}`

Delete a user. Platform admin only.

Parameter	In	Type	Required	Description
`id`	path	string	yes

POST `/users/{id}/reset-password`

Reset a user's password. Platform admin only.

Parameter	In	Type	Required	Description
`id`	path	string	yes

Request body (JSON):

Any JSON object (see the app for fields).

POST `/users/{id}/suspend`

Suspend a user. Platform admin only.

Parameter	In	Type	Required	Description
`id`	path	string	yes

POST `/users/{id}/activate`

Re-activate a user. Platform admin only.

Parameter	In	Type	Required	Description
`id`	path	string	yes

POST `/users/{id}/memberships`

Add a membership. Platform admin only.

Parameter	In	Type	Required	Description
`id`	path	string	yes

Request body (JSON):

Parameter	Type	Required	Description
`tenant_id`	string	yes
`role`	string	yes

DELETE `/users/{id}/memberships/{tid}`

Remove a membership. Platform admin only.

Parameter	In	Type	Required	Description
`id`	path	string	yes
`tid`	path	string	yes

DELETE `/users/{id}/sessions/{sid}`

Sign out a user's session. Platform admin only.

Parameter	In	Type	Required	Description
`id`	path	string	yes
`sid`	path	string	yes

GET `/audit`

Audit trail. Platform admin only. MCP tool: list_audit_log.

Parameter	In	Type	Required
`page`	query	string	no
`page_size`	query	string	no
`q`	query	string	no
`sort`	query	string	no
`dir`	query	`asc` \| `desc`	no
`action`	query	string	no

GET `/errors`

Tracked errors. Platform admin only. MCP tool: list_errors.

Parameter	In	Type	Required
`page`	query	string	no
`page_size`	query	string	no
`q`	query	string	no
`sort`	query	string	no
`dir`	query	`asc` \| `desc`	no

GET `/errors/{id}`

One tracked error. Platform admin only.

Parameter	In	Type	Required	Description
`id`	path	string	yes

PATCH `/errors/{id}`

Resolve or reopen an error. Platform admin only. MCP tool: resolve_error.

Parameter	In	Type	Required	Description
`id`	path	string	yes

Request body (JSON):

Parameter	Type	Required	Description
`resolved`	boolean	yes

DELETE `/errors/{id}`

Delete a tracked error. Platform admin only.

Parameter	In	Type	Required	Description
`id`	path	string	yes

POST `/users/{id}/approve`

Approve a pending account. Platform admin only.

Parameter	In	Type	Required	Description
`id`	path	string	yes

POST `/users/{id}/decline`

Decline a pending account. Platform admin only.

Parameter	In	Type	Required	Description
`id`	path	string	yes

POST `/credits/requests/{id}/approve`

Approve a credit request. Platform admin only.

Parameter	In	Type	Required	Description
`id`	path	string	yes

POST `/credits/requests/{id}/decline`

Decline a credit request. Platform admin only.

Parameter	In	Type	Required	Description
`id`	path	string	yes

Request body (JSON):

Parameter	Type	Required	Description
`note`	string	no

POST `/credits/requests/{id}/refund`

Refund an approved pack: takes back its unspent credits (platform admin). Platform admin only.

Parameter	In	Type	Required	Description
`id`	path	string	yes

Request body (JSON):

Parameter	Type	Required	Description
`note`	string	no

GET `/upstream/balance`

Upstream balances: Standard scans (USD), Live scans (searches left), Pilot Crawl. Platform admin only.

Parameter	In	Type	Required	Description
`refresh`	query	string	no	1 = bypass the 5-minute cache

PUT `/tenants/{id}/plan`

Set a workspace's plan (platform admin override; Stripe sets it automatically once payments are live). Platform admin only.

Parameter	In	Type	Required	Description
`id`	path	string	yes

Request body (JSON):

Parameter	Type	Required	Description
`plan`	`free` \| `agency_starter` \| `agency_pro` \| `agency_scale`	yes
`status`	`active` \| `past_due` \| `canceled`	no
`interval`	`month` \| `year` \| null	no
`current_period_end`	string \| null	no
`grace_until`	string \| null	no
`grant_period`	boolean	no	Also grant one period of plan credits
`period_start`	string	no
`period_end`	string	no
`ref`	string	no	Idempotency key for the grant

GET `/admin/margin`

Margin dashboard: revenue vs upstream cost, index and credit-back rates, free-tier cost, upstream utilisation, reconciliation. Platform admin only.

Parameter	In	Type	Required
`from`	query	string	no
`to`	query	string	no
`days`	query	string	no

GET `/admin/margin/settings`

Upstream tier, $/indexed link, monthly allowance and check rates. Platform admin only.

PUT `/admin/margin/settings`

Update upstream tier, $/indexed link, monthly allowance and check rates. Platform admin only.

Request body (JSON):

Parameter	Type	Required
`tier`	string \| null	no
`cost_per_indexed_usd`	number \| null	no
`monthly_allowance`	integer (≥-9007199254740991, ≤9007199254740991) \| null	no
`standard_check_usd`	number	no
`live_check_usd`	number	no

PUT `/admin/margin/reconciliation/{month}`

Enter the upstream billed count for a month (YYYY-MM). Platform admin only.

Parameter	In	Type	Required	Description
`month`	path	string	yes

Request body (JSON):

Parameter	Type	Required	Description
`billed_count`	integer (≥-9007199254740991, ≤9007199254740991) \| null	yes
`note`	string	no

POST `/billing/tick`

Run the guarantee re-checks and credit housekeeping now (platform admin). Platform admin only.