Open API

Build compliance checks into your own systems

The US site Open API provides compliance checks for English text, video and images on TikTok US, Amazon and your own store, and in Meta, Google and TikTok ads, along with custom word lists, AI rewrites and batch checks, through one set of REST endpoints. It uses the same detection engine and credit account as the web app, so the API returns the same results you see on the web.

Base URLhttps://www.byerisk.com/api/v1/intl/usCreate an API key OpenAPI spec (JSON) →

Quick start

Three steps. Every check follows the same pattern: submit to get an id, then poll for the result.

Create an API key

Create one on the Open API page of your dashboard. Keys look like brsk_live_… and are shown only once, when they are created. Save the key to your secrets manager right away.

Send the authorization header

Add Authorization: Bearer brsk_live_… to every request. This key is not the same as the token from a web sign-in, and the two cannot be used in place of each other.

Submit a check and poll for the result

The submit call returns an id immediately and the check runs in the background. Poll the GET endpoint until status is completed. Text checks usually take 3–15 seconds; video checks take about half the video’s duration.

Submit a text check

bash

curl -X POST https://www.byerisk.com/api/v1/intl/us/text/checks \
  -H "Authorization: Bearer $BYERISK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "These gummies cure joint pain and are clinically proven to melt belly fat in 7 days. Results guaranteed!",
    "platform": "tiktok_us",
    "vertical": "supplement",
    "explainLocale": "en-US"
  }'

# → {"success":true,"data":{"id":"cm5abc…","status":"processing"}}

Poll for the result

bash

curl https://www.byerisk.com/api/v1/intl/us/text/checks/cm5abc… \
  -H "Authorization: Bearer $BYERISK_API_KEY"

# status = completed:
# {
#   "success": true,
#   "data": {
#     "status": "completed",
#     "riskLevel": "medium",
#     "summary": { "violation": 5, "sceneHint": 0, "custom": 0 },
#     "risks": [
#       {
#         "kind": "violation",
#         "severity": "high",
#         "matchedText": "cure",
#         "startIndex": 14,
#         "endIndex": 18,
#         "category": "Cure wording",
#         "legalRef": "21 U.S.C. §343(r)(6); 21 CFR 101.93(f)–(g); FTC Act §12, 15 U.S.C. §52"
#       }
#     ]
#   }
# }

Every response uses the same envelope. Success is { "success": true, "data": … } and failure is { "success": false, "error": "…" }. The Response field tables in the endpoint reference below describe the contents of data.

Sites and keys

This is the most important thing to know before you integrate: each API key belongs to one site. A key created in the US site dashboard can call endpoints under /v1/intl/us/ only. Using it on the Indonesia site (/v1/intl/id/) or the China site (/v1/) returns 401, and the reverse is also true.

Why keys are bound to a site. The sites are separate products: routes, platform values, rule libraries, plans and credit accounts are all separate. A key that worked everywhere would leave "whose credits to deduct and which rules to apply" to be guessed from the request body, and both wrong guesses fail silently: English copy checked against another site’s rule sets almost always passes, or credits come out of another site’s account. Binding keys to a site stops both cases at the first step.

Item	Isolated per site?	Notes
API key	Yes	Issued separately on each site; cross-site calls return 401
Credit balance, plan	Yes	Balances on other sites cannot be used here, and a plan does not unlock other sites
Check history, custom word list	Yes	The same term is stored separately on each site and never matches on another site
Word list quota, master switch	No	Account-level settings, shared across sites
The account itself (email, sign-in)	No	One ByeRisk account can do business on several sites

Risk verdicts

This is the most common integration mistake: riskLevel for text checks and for image / video checks is not the same enum. The two come from different assessment pipelines and cannot be converted into each other. Handle them per endpoint rather than defining a single riskLevel enum.

Endpoint	riskLevel values	Meaning
Text checks	safe / low / medium / high	The highest severity among matched violations
Image and video checks	PASS / REVIEW / REJECT	The handling recommendation from content moderation

Two dimensions on each risk

kind

Risk kind

violation is a hard violation of federal rules or platform policy and must be fixed; scene-hint is a context-dependent note. Only violations count toward riskLevel.

severity

Severity

Three levels: high / medium / low. The top-level riskLevel is the highest level among all violations.

customRisks

Custom term matches

Terms you configure yourself are grouped separately and do not count toward riskLevel. They reflect your preferences, not a compliance assessment.

Why custom terms are kept separate. Competitor names and internally banned phrases are business preferences. Mixing them into the same list as "violates US rules" would leave your downstream systems unable to tell "must block" from "worth a reminder". They are therefore returned separately in customRisks, and terms with a replacement include replacement for an exact substitution.

Explanations follow explainLocale. Risk explanations, suggested fixes and legalRef are returned in English or Chinese according to explainLocale (en-US or zh-CN). If omitted, it defaults to zh-CN, so pass en-US for English. Citations are identical in both languages (for example 21 CFR 101.93); the Chinese version adds a one-sentence explanation in Chinese, so every reference can still be verified.

What is checked

Each dimension has its own assessment pipeline. Unlike the China site, there are no parameters for trimming check dimensions: the visual and audio policies are tied to account-side configuration, so a dimension parameter would not change what actually runs. It would be a switch that does nothing.

Dimension	Coverage	Notes
Text	US regulation and platform policy rule library + AI semantic review	Federal rules such as FTC and FDA requirements, plus TikTok Shop, Amazon, and Meta, Google and TikTok ad policies. AI semantic review handles cross-sentence risks and filters false positives. State laws are not covered
Images	Visual risks + text recognition on images	Detects prohibited items, and contact details, drug or sexual wording shown on the image
Video	Visual frames + voiceover	The voiceover is transcribed and checked by the same engine as text checks. English audio is not moderated as audio

Image checks do not assess commercial compliance. They assess the risk of the visuals themselves. They do not verify efficacy claims, "FDA approved" or certification marks, which require reading and judging the copy on the image. Submit that copy separately as a text check. We would rather state this limit here than let you assume that a passing image check means the whole asset is compliant.

English audio is not moderated as audio. For English videos, audios does not report risks. Claims made in the voiceover appear in transcriptRisks, which uses the same rules and AI semantic review as text checks. Do not read the absence of audio findings as "the audio is compliant".

Video polling has two stop conditions. status has reached a final state and transcriptStatus is no longer processing. Transcription usually finishes after visual moderation; if you check status alone, you will never receive transcriptRisks.

Multi-tenant integration

If you build compliance checks into your own product and offer them to several of your own customers, add an X-End-Tenant header with the tenant ID from your system, and we create a separate isolated scope for each tenant ID. You do not need a separate API key for each customer.

bash

curl -X POST https://www.byerisk.com/api/v1/intl/us/text/checks \
  -H "Authorization: Bearer $BYERISK_API_KEY" \
  -H "X-End-Tenant: store-4271" \
  -H "Content-Type: application/json" \
  -d '{ "text": "…", "platform": "tiktok_us", "vertical": "general" }'

Item	Belongs to	Notes
Custom word list	Each tenant	Terms configured for tenant A never match tenant B’s checks
Check history, upload directory	Each tenant	List endpoints return only the records of the current X-End-Tenant; tenants cannot see each other’s data
Credit balance, plan	Your main account	Credits are deducted from your own balance; you do not need to top up each end tenant
Rate limits	Per API key	All end tenants share the limits of one key; create more keys if you need more throughput

Send a stable tenant identifier. A tenant ID is created automatically the first time it appears, with no registration step. Allowed values are 1–64 letters, digits and _ . : -. If you send a value that changes on every request (for example, a request ID sent by mistake), you will quickly exhaust the per-key limit on isolated scopes and start receiving errors. Without this header, all data stays in your own single scope, exactly as if the feature were not used.

Billing and rate limits

The API shares this site’s credit balance with the web app, at the same prices. Before you integrate, you can call GET /v1/intl/us/account to check your balance and this month’s usage.

Action	Cost
Text check	Plan rate, per call
AI rewrite	Plan rate, per call
Video check	1 credit per second
Image check	2 credits per image
Batch check	Each item is billed at its own rate
Custom word list management, account queries, upload credentials	Free

Rate limits apply per API key: submissions 60 per minute, queries 600 per minute, configuration 120 per minute. Each tier is counted separately, every response includes X-RateLimit-Remaining, and exceeding a limit returns 429 with Retry-After.

Two plan requirements. Creating API keys and running batch checks both require the Premium plan or higher on this site. Plans are isolated by site; a subscription on another site does not unlock access here. Keys that have already been issued are not affected by changes to this requirement and keep working.

Error codes

Status code	Meaning	What to do
400	Invalid parameters, including a platform, category or explanation language that does not belong to this site	Fix the parameters as described in error
401	The key is invalid, revoked or expired, or does not belong to the site you are calling	Check whether the error mentions a site mismatch before replacing the key
402	Insufficient credits	Top up, then retry
403	The feature requires a higher plan	Upgrade your plan on this site
404	The record does not exist, does not belong to your account, or belongs to another site	Check the id and the site segment of the path
429	Rate limit exceeded	Back off and retry after Retry-After
500	Server error	Safe to retry; contact us if it keeps failing

For AI agents

One design goal of this API is that AI agents can read and call it on their own. The spec is standard OpenAPI 3.0, and parameters, responses, enum values and error semantics are all described in it, so no separate adapter documentation is needed.

Give the spec URL to your agent (Claude, GPT, Coze, Dify and others can import tools from OpenAPI) together with an API key, and it can run the full loop of "check → read the risks → revise the copy → check again" on its own:

Prompt

Read the OpenAPI spec at https://www.byerisk.com/api/v1/intl/us/openapi.json?lang=en-US,
then use my API key to call the ByeRisk US site.
Check whether the following English sales copy is compliant,
list each risk that must be fixed, and suggest a compliant rewrite.

The spec URL carries a lang parameter that follows your current interface language, so the version you give your agent determines the language of the descriptions it reads. The spec is public and requires no authentication.

https://www.byerisk.com/api/v1/intl/us/openapi.json?lang=en-US

Text checks

POST/v1/intl/us/text/checks

Submit a text check

Submits text for a compliance check and returns an ID immediately; the check runs asynchronously in the background. After you receive the ID, poll GET {id} until status becomes completed or failed (usually 3–15 seconds).

The check evaluates the English content itself; the language of the risk explanations is determined by explainLocale, and the two do not affect each other. Credits are deducted on submission; if queuing fails, they are refunded in full automatically.

Request body

Field	Type	Description
textRequired	string	The text to check, 10–5,000 characters. The English content itself is checked, independent of the explanation language below. (length 10–5000)
platformRequired	enum	The platform where the content will be published. Determines which platform rule set applies.Allowed values: `tiktok_us`TikTok US`amazon_us`Amazon US`dtc_us`Your own store`meta_ads`Meta Ads`google_ads`Google Ads`tiktok_ads`TikTok Ads
verticalRequired	enum	Content category. A specific category applies the rule sets for all categories plus that category's own rule sets; general applies the rule sets of every category (erring on the side of reporting more, with AI semantic review filtering false positives).Allowed values: `general`General`beauty`Beauty & personal care`health`Health & wellness`supplement`Dietary supplements`weight_loss`Weight loss`baby`Baby & kids`apparel`Apparel & textiles`jewelry`Jewelry`home`Home & cleaning`pet`Pet
explainLocale	enum	The language of risk explanations and suggested fixes. It is independent of the language of the content: the text checked is always English, and this parameter only sets the language used to explain the results. Defaults to zh-CN if omitted; pass en-US for English explanations.Allowed values: `zh-CN`Chinese (Simplified)`en-US`EnglishDefault `zh-CN`

Response201

Field	Type	Description
id	string	ID of this check, used to poll for the result.
object	string	Object type.
status	string	Current status. It is processing immediately after submission.

Possible errors

402Insufficient credits

Example

bash

curl -X POST https://www.byerisk.com/api/v1/intl/us/text/checks \
  -H "Authorization: Bearer $BYERISK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "These gummies cure joint pain and are clinically proven to melt belly fat in 7 days. Results guaranteed!",
    "platform": "tiktok_us",
    "vertical": "supplement",
    "explainLocale": "zh-CN"
  }'

json — response

{
  "success": true,
  "data": {
    "id": "cms8xhc5x0006sp59vrks7zkf",
    "object": "intl_text_check",
    "status": "processing"
  }
}

GET/v1/intl/us/text/checks

List text checks

Returns a paginated list sorted by creation time, newest first, containing summary fields only (the text excerpt is truncated to 100 characters). Only records from this site are returned.

Query parameters

Field	Type	Description
page	string	Page number, starting at 1.Default `1`
pageSize	string	Number of items per page, up to 50.Default `20`

Response200

Field	Type	Description
object	string	Object type. Always list.
page	number	Current page number.
pageSize	number	Number of items per page.
total	number	Total number of matching items.
hasMore	boolean	Whether there is another page.
data	array<object>	Items on this page.
└id	string	Check ID.
└object	string	Object type.
└status	string	Status.
└platform	string	Publishing platform.
└vertical	object	Content category.
└preview	string	Text excerpt (truncated to 100 characters). Retrieve the check details for the full text.
└riskLevel	enum	Top-level verdict.Allowed values: `safelowmediumhigh`
└riskCount	number	Number of risks.
└fixStatus	object	AI rewrite status.
└createdAt	object	Creation time.

Example

bash

curl "https://www.byerisk.com/api/v1/intl/us/text/checks" \
  -H "Authorization: Bearer $BYERISK_API_KEY"

json — response

{
  "success": true,
  "data": {
    "object": "list",
    "page": 1,
    "pageSize": 20,
    "total": 128,
    "hasMore": true,
    "data": [
      {
        "id": "string",
        "object": "intl_text_check",
        "status": "string",
        "platform": "string",
        "vertical": null,
        "preview": "string",
        "riskLevel": "safe",
        "riskCount": 0,
        "fixStatus": null,
        "createdAt": null
      }
    ]
  }
}

GET/v1/intl/us/text/checks/{id}

Get a text check result

When status is processing, the check is still running; retry later. risks holds the final result only when status is completed.

Risks are reported in two layers that are kept strictly separate:

- risks — compliance risks. kind=violation is a hard violation; kind=scene-hint is a scene hint (a scenario-specific restriction).

- customRisks — matches against the custom rule terms you configured. They are not counted toward riskLevel; if you configured a replacement, replacement is provided.

Path parameters

Field	Type	Description
idRequired	string

Response200

Field	Type	Description
id	string	Check ID.
object	string	Object type.
status	enum	`processing` means the check is still running; retry later. risks holds the final result only when the status is `completed`.Allowed values: `processing`Processing`completed`Completed`failed`Failed
platform	enum	Publishing platform.Allowed values: `tiktok_us`TikTok US`amazon_us`Amazon US`dtc_us`Your own store`meta_ads`Meta Ads`google_ads`Google Ads`tiktok_ads`TikTok Ads
vertical	enum	Content category.Allowed values: `general`General`beauty`Beauty & personal care`health`Health & wellness`supplement`Dietary supplements`weight_loss`Weight loss`baby`Baby & kids`apparel`Apparel & textiles`jewelry`Jewelry`home`Home & cleaning`pet`Pet
text	string	The original text that was checked.
riskLevel	enum	Top-level verdict, derived from the highest severity among violation risks. ⚠️ This is not the same set of values as `PASS` / `REVIEW` / `REJECT` for images and videos.Allowed values: `safelowmediumhigh`
summary	object	Counts by type.
└violation	number	Number of hard violations of laws / platform rules.
└sceneHint	number	Number of scene hints.
└custom	number	Number of matches from your custom word list. Not counted toward riskLevel.
└semantic	number	Number of semantic risk labels (overall notices that cannot be located at a specific position).
risks	array<object>	Compliance risks, one entry per risk.
└id	object	Risk ID.
└kind	enum	Risk kind: `violation` is a hard violation of laws / platform rules (must be fixed); `scene-hint` is a scene hint (a scenario-specific restriction).Allowed values: `violation`Violation`scene-hint`Scene hint
└severity	enum	Severity. The top-level `riskLevel` takes the highest severity among all violations.Allowed values: `high`High`medium`Medium`low`Low
└matchedText	string	The matched snippet of the original text.
└startIndex	number	Start index of the matched snippet in the original text. For semantic matches that cannot be located, this is `-1` (not null). In that case, search the original text for `matchedText` yourself, or display the risk only as an overall notice.
└endIndex	number	End index of the matched snippet; this can also be `-1`.
└category	object	Risk category, localized according to explainLocale.
└suggestion	object	Suggested fix, localized according to explainLocale.
└legalRef	object	Legal or platform policy reference, returned in the explainLocale language. Citations are identical in both languages; the Chinese version adds a one-sentence explanation in Chinese.
└source	enum	Source of the finding: `rule` is a deterministic rule match; `model` is a model judgment; `custom` is a custom term.Allowed values: `rulemodelcustom`
customRisks	array<object>	Matches from your custom word list. Separate from risks and not counted toward riskLevel: they reflect your own preferences, not a compliance judgment.
└matchedText	string	The matched snippet of the original text.
└startIndex	number	Start index (can be -1).
└endIndex	number	End index (can be -1).
└replacement	object	The replacement you configured for this term. Empty means flag only, with no suggested replacement.
└note	object	The note you wrote for this term.
semanticLabels	array<string>	Overall notices for risks that the model identified but could not locate in a specific snippet.
fixStatus	object	AI rewrite status: null = not triggered \| processing = rewrite in progress \| completed = finished \| failed = failed.
fixedText	object	Full text after the AI rewrite. Populated only after the rewrite completes.
createdAt	object	Creation time (ISO 8601).
updatedAt	object	Last update time (ISO 8601).

Possible errors

404The record does not exist, does not belong to your account, or belongs to another site

Example

bash

curl "https://www.byerisk.com/api/v1/intl/us/text/checks/{id}" \
  -H "Authorization: Bearer $BYERISK_API_KEY"

json — response

{
  "success": true,
  "data": {
    "id": "string",
    "object": "intl_text_check",
    "status": "processing",
    "platform": "tiktok_us",
    "vertical": "general",
    "text": "string",
    "riskLevel": "safe",
    "summary": {
      "violation": 3,
      "sceneHint": 1,
      "custom": 0,
      "semantic": 2
    },
    "risks": [
      {
        "id": null,
        "kind": "violation",
        "severity": "high",
        "matchedText": "cure",
        "startIndex": 14,
        "endIndex": 18,
        "category": null,
        "suggestion": null,
        "legalRef": "21 U.S.C. §343(r)(6); 21 CFR 101.93(f)–(g); FTC Act §12, 15 U.S.C. §52",
        "source": "rule"
      }
    ],
    "customRisks": [
      {
        "matchedText": "string",
        "startIndex": 0,
        "endIndex": 0,
        "replacement": null,
        "note": null
      }
    ],
    "semanticLabels": [
      "string"
    ],
    "fixStatus": null,
    "fixedText": null,
    "createdAt": null,
    "updatedAt": null
  }
}

DELETE/v1/intl/us/text/checks/{id}

Delete a text check

This action cannot be undone.

Path parameters

Field	Type	Description
idRequired	string

Response200

Field	Type	Description
id	string	ID of the deleted record.
object	string	Object type.
deleted	boolean	Always true.

Possible errors

404The record does not exist or belongs to another site

Example

bash

curl -X DELETE https://www.byerisk.com/api/v1/intl/us/text/checks/{id} \
  -H "Authorization: Bearer $BYERISK_API_KEY"

json — response

{
  "success": true,
  "data": {
    "id": "string",
    "object": "intl_text_check",
    "deleted": true
  }
}

POST/v1/intl/us/text/checks/{id}/fix

Trigger an AI rewrite

Triggers an AI rewrite for a completed check and returns immediately; the rewrite runs in the background. Poll GET {id}; when the rewrite finishes, the result is in fixedText (fixStatus becomes completed). The rewrite deducts additional credits, which are refunded automatically if it fails.

Path parameters

Field	Type	Description
idRequired	string

Response201

Field	Type	Description
id	string	Check ID.
object	string	Object type.
fixStatus	string	Rewrite status. It is processing once the request is accepted.
creditCost	number	Credits consumed by this rewrite.

Possible errors

400The record does not need a rewrite (it has no violations), or a rewrite is already in progress

402Insufficient credits

404The record does not exist or belongs to another site

Example

bash

curl -X POST https://www.byerisk.com/api/v1/intl/us/text/checks/{id}/fix \
  -H "Authorization: Bearer $BYERISK_API_KEY"

json — response

{
  "success": true,
  "data": {
    "id": "string",
    "object": "intl_text_check",
    "fixStatus": "processing",
    "creditCost": 2
  }
}

Image checks

POST/v1/intl/us/image/checks

Submit an image check

Submits a publicly accessible image URL for a compliance check.

Image checks complete synchronously: when this endpoint returns, the result is already available and the response body is the complete check result, so there is no need to poll. (GET {id} remains available for later lookups.)

**Always check status**: it is normally completed; if the engine fails, it is failed (in that case the credits have been refunded automatically and labels is empty). The endpoint still returns 201 rather than 5xx in this case, because the record itself was created successfully.

Billing: 2 credits per image.

Request body

Field	Type	Description
imageUrlRequired	string	Image URL. It must be publicly accessible (our check service must be able to fetch it directly). If you do not have your own object storage, first call `POST /v1/intl/{country}/uploads/policy` to get direct-upload credentials.
imageTitleRequired	string	Image title / file name, used to identify the image in your history.
imageSizeRequired	number	Image size in bytes. (minimum 1)
imageWidth	number	Image width in pixels.
imageHeight	number	Image height in pixels.
vertical	enum	Declared content category. It does not affect the visual assessment for this check (the visual policy is tied to account-side configuration and is independent of category); it is used only for record-keeping and for display in your history. Fill it in accurately, or leave it empty.Allowed values: `general`General`beauty`Beauty & personal care`health`Health & wellness`supplement`Dietary supplements`weight_loss`Weight loss`baby`Baby & kids`apparel`Apparel & textiles`jewelry`Jewelry`home`Home & cleaning`pet`Pet
explainLocale	enum	Language in which risk labels are returned. Same as for text checks; unrelated to the language of any text in the image.Allowed values: `zh-CN`Chinese (Simplified)`en-US`EnglishDefault `zh-CN`

Response201

Field	Type	Description
id	string	Check ID.
object	string	Object type.
status	enum	Always check this field: if the engine fails, it is `failed` (credits have been refunded automatically and labels is empty), and the endpoint still returns 201.Allowed values: `processing`Processing`completed`Completed`failed`Failed
image	object	Image information.
└url	string	Image URL (the one you submitted).
└title	string	Image title / file name.
└sizeBytes	object	Size in bytes.
└width	object	Width in pixels.
└height	object	Height in pixels.
vertical	enum	Category declared at submission. Recorded only; it does not affect the visual assessment.Allowed values: `general`General`beauty`Beauty & personal care`health`Health & wellness`supplement`Dietary supplements`weight_loss`Weight loss`baby`Baby & kids`apparel`Apparel & textiles`jewelry`Jewelry`home`Home & cleaning`pet`Pet
riskLevel	enum	Top-level verdict. ⚠️ This is not the same set of values as safe/low/medium/high for text checks.Allowed values: `PASSREVIEWREJECT`
labels	array<object>	Matched risk labels. An empty array when there are no risks.
└description	string	Risk label, localized according to explainLocale.
└riskLevel	enum	This label's own risk level. Older records have no per-label risk level; in that case this is null (no value is made up).Allowed values: `PASSREVIEWREJECT`
createdAt	object	Creation time.
updatedAt	object	Last update time.

Possible errors

400Invalid parameters

402Insufficient credits

Example

bash

curl -X POST https://www.byerisk.com/api/v1/intl/us/image/checks \
  -H "Authorization: Bearer $BYERISK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl": "https://cdn.example.com/products/serum-01.jpg",
    "imageTitle": "serum-01.jpg",
    "imageSize": 254112,
    "imageWidth": 1080,
    "imageHeight": 1080,
    "vertical": "general",
    "explainLocale": "zh-CN"
  }'

json — response

{
  "success": true,
  "data": {
    "id": "string",
    "object": "intl_image_check",
    "status": "processing",
    "image": {
      "url": "string",
      "title": "string",
      "sizeBytes": null,
      "width": null,
      "height": null
    },
    "vertical": "general",
    "riskLevel": "PASS",
    "labels": [
      {
        "description": "Sexual content",
        "riskLevel": "PASS"
      }
    ],
    "createdAt": null,
    "updatedAt": null
  }
}

GET/v1/intl/us/image/checks

List image checks

Returns a paginated list sorted by creation time, newest first, containing summary fields only.

Query parameters

Field	Type	Description
page	string	Page number, starting at 1.Default `1`
pageSize	string	Number of items per page, up to 50.Default `20`

Response200

Field	Type	Description
object	string	Object type. Always list.
page	number	Current page number.
pageSize	number	Number of items per page.
total	number	Total number of matching items.
hasMore	boolean	Whether there is another page.
data	array<object>	Items on this page.
└id	string	Check ID.
└object	string	Object type.
└status	string	Status.
└image	object	Image URL and title.
└vertical	object	Declared category.
└riskLevel	enum	Top-level verdict.Allowed values: `PASSREVIEWREJECT`
└labels	array<string>	Risk label text (the list does not include per-label risk levels).
└createdAt	object	Creation time.

Example

bash

curl "https://www.byerisk.com/api/v1/intl/us/image/checks" \
  -H "Authorization: Bearer $BYERISK_API_KEY"

json — response

{
  "success": true,
  "data": {
    "object": "list",
    "page": 1,
    "pageSize": 20,
    "total": 128,
    "hasMore": true,
    "data": [
      {
        "id": "string",
        "object": "intl_image_check",
        "status": "string",
        "image": null,
        "vertical": null,
        "riskLevel": "PASS",
        "labels": [
          "string"
        ],
        "createdAt": null
      }
    ]
  }
}

GET/v1/intl/us/image/checks/{id}

Get an image check result

Retrieves a previously submitted image check.

Path parameters

Field	Type	Description
idRequired	string

Response200

Field	Type	Description
id	string	Check ID.
object	string	Object type.
status	enum	Always check this field: if the engine fails, it is `failed` (credits have been refunded automatically and labels is empty), and the endpoint still returns 201.Allowed values: `processing`Processing`completed`Completed`failed`Failed
image	object	Image information.
└url	string	Image URL (the one you submitted).
└title	string	Image title / file name.
└sizeBytes	object	Size in bytes.
└width	object	Width in pixels.
└height	object	Height in pixels.
vertical	enum	Category declared at submission. Recorded only; it does not affect the visual assessment.Allowed values: `general`General`beauty`Beauty & personal care`health`Health & wellness`supplement`Dietary supplements`weight_loss`Weight loss`baby`Baby & kids`apparel`Apparel & textiles`jewelry`Jewelry`home`Home & cleaning`pet`Pet
riskLevel	enum	Top-level verdict. ⚠️ This is not the same set of values as safe/low/medium/high for text checks.Allowed values: `PASSREVIEWREJECT`
labels	array<object>	Matched risk labels. An empty array when there are no risks.
└description	string	Risk label, localized according to explainLocale.
└riskLevel	enum	This label's own risk level. Older records have no per-label risk level; in that case this is null (no value is made up).Allowed values: `PASSREVIEWREJECT`
createdAt	object	Creation time.
updatedAt	object	Last update time.

Possible errors

404The record does not exist or belongs to another site

Example

bash

curl "https://www.byerisk.com/api/v1/intl/us/image/checks/{id}" \
  -H "Authorization: Bearer $BYERISK_API_KEY"

json — response

{
  "success": true,
  "data": {
    "id": "string",
    "object": "intl_image_check",
    "status": "processing",
    "image": {
      "url": "string",
      "title": "string",
      "sizeBytes": null,
      "width": null,
      "height": null
    },
    "vertical": "general",
    "riskLevel": "PASS",
    "labels": [
      {
        "description": "Sexual content",
        "riskLevel": "PASS"
      }
    ],
    "createdAt": null,
    "updatedAt": null
  }
}

DELETE/v1/intl/us/image/checks/{id}

Delete an image check

Soft-deletes the check and asynchronously removes the uploaded image file.

Path parameters

Field	Type	Description
idRequired	string

Response200

Field	Type	Description
id	string	ID of the deleted record.
object	string	Object type.
deleted	boolean	Always true.

Possible errors

404The record does not exist or belongs to another site

Example

bash

curl -X DELETE https://www.byerisk.com/api/v1/intl/us/image/checks/{id} \
  -H "Authorization: Bearer $BYERISK_API_KEY"

json — response

{
  "success": true,
  "data": {
    "id": "string",
    "object": "intl_text_check",
    "deleted": true
  }
}

Video checks

POST/v1/intl/us/video/checks

Submit a video check

Submits a publicly accessible video URL for a compliance check and returns an ID immediately; the check runs asynchronously in the background.

Poll GET {id}. A check takes about half the video's duration (at least 30 seconds); poll every 5–10 seconds.

The check covers visual frames (frames) and the voiceover (transcriptRisks, transcribed and checked by the same engine as text checks).

English audio is not moderated as audio, so audios does not report risks; claims made in the voiceover appear in transcriptRisks.

Billing: 1 credit per second of video, deducted on submission. Report videoDuration accurately.

Request body

Field	Type	Description
videoUrlRequired	string	Video URL. It must be publicly accessible. If you do not have your own object storage, first call the direct-upload credentials endpoint.
videoTitleRequired	string	Video title / file name.
videoSizeRequired	number	Video size in MB (not bytes). Maximum 1024 (1GB). (range 0.01–1024)
videoDurationRequired	number	Video duration in seconds. Billing is based on this value (1 credit per second), so report it accurately. (minimum 1)
videoWidth	number	Video width in pixels.
videoHeight	number	Video height in pixels.
platform	enum	Publishing platform. It determines only which platform rule set applies to the voiceover; if omitted, this site's default platform is used.Allowed values: `tiktok_us`TikTok US`amazon_us`Amazon US`dtc_us`Your own store`meta_ads`Meta Ads`google_ads`Google Ads`tiktok_ads`TikTok Ads
vertical	enum	Content category. It determines only which category rule sets apply to the voiceover: a specific category applies the rule sets for all categories plus that category's own rule sets; if omitted or general, the rule sets of every category apply (erring on the side of reporting more). It has no effect on the visual or audio assessment.Allowed values: `general`General`beauty`Beauty & personal care`health`Health & wellness`supplement`Dietary supplements`weight_loss`Weight loss`baby`Baby & kids`apparel`Apparel & textiles`jewelry`Jewelry`home`Home & cleaning`pet`Pet

Response201

Field	Type	Description
id	string	ID of this check, used to poll for the result.
object	string	Object type.
status	string	Current status. It is processing immediately after submission.

Possible errors

402Insufficient credits

Example

bash

curl -X POST https://www.byerisk.com/api/v1/intl/us/video/checks \
  -H "Authorization: Bearer $BYERISK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "videoUrl": "https://cdn.example.com/videos/promo-01.mp4",
    "videoTitle": "promo-01.mp4",
    "videoSize": 12.4,
    "videoDuration": 45,
    "videoWidth": 1080,
    "videoHeight": 1920,
    "platform": "tiktok_us",
    "vertical": "general"
  }'

json — response

{
  "success": true,
  "data": {
    "id": "cms8xhc5x0006sp59vrks7zkf",
    "object": "intl_text_check",
    "status": "processing"
  }
}

GET/v1/intl/us/video/checks

List video checks

Returns a paginated list sorted by creation time, newest first, containing summary fields only.

Query parameters

Field	Type	Description
page	string	Page number, starting at 1.Default `1`
pageSize	string	Number of items per page, up to 50.Default `20`
status	enum	Filter by status.Allowed values: `processing`Processing`completed`Completed`failed`Failed

Response200

Field	Type	Description
object	string	Object type. Always list.
page	number	Current page number.
pageSize	number	Number of items per page.
total	number	Total number of matching items.
hasMore	boolean	Whether there is another page.
data	array<object>	Items on this page.
└id	string	Check ID.
└object	string	Object type.
└status	string	Video review status.
└video	object	Video URL, title, and duration.
└vertical	object	Declared category.
└riskLevel	enum	Top-level verdict.Allowed values: `PASSREVIEWREJECT`
└labels	array<string>	Risk labels.
└transcriptStatus	object	Voiceover transcription status.
└createdAt	object	Creation time.

Example

bash

curl "https://www.byerisk.com/api/v1/intl/us/video/checks" \
  -H "Authorization: Bearer $BYERISK_API_KEY"

json — response

{
  "success": true,
  "data": {
    "object": "list",
    "page": 1,
    "pageSize": 20,
    "total": 128,
    "hasMore": true,
    "data": [
      {
        "id": "string",
        "object": "intl_video_check",
        "status": "string",
        "video": null,
        "vertical": null,
        "riskLevel": "PASS",
        "labels": [
          "string"
        ],
        "transcriptStatus": null,
        "createdAt": null
      }
    ]
  }
}

GET/v1/intl/us/video/checks/{id}

Get a video check result

Each call also advances polling against the check engine by one step, so you can poll this endpoint directly; no separate status endpoint is needed.

⚠️ Polling has two stop conditions: status reaches a terminal state (completed / failed), and transcriptStatus is no longer processing. Voiceover transcription usually finishes after the visual review. If you check only status, you will stop while the voiceover is still being transcribed and never receive transcriptRisks.

explainLocale determines the language used to explain voiceover risks. It is a read-side parameter rather than a submit-side one because results are produced asynchronously, and a language chosen at submission time would not carry through to the time the results are stored.

Path parameters

Field	Type	Description
idRequired	string

Query parameters

Field	Type	Description
explainLocale	enum	Language in which risk explanations are returned. Defaults to zh-CN if omitted.Allowed values: `zh-CN`Chinese (Simplified)`en-US`EnglishDefault `zh-CN`

Response200

Field	Type	Description
id	string	Check ID.
object	string	Object type.
status	enum	Video review status. ⚠️ It is not the only stop condition for polling: you must also check `transcriptStatus`, because voiceover transcription usually finishes after the visual review.Allowed values: `processing`Processing`completed`Completed`failed`Failed
video	object	Video information.
└url	string	Video URL.
└title	string	Video title / file name.
└sizeMb	object	Size (MB).
└durationSeconds	object	Duration (seconds).
└width	object	Width in pixels.
└height	object	Height in pixels.
platform	enum	Platform used to check the voiceover.Allowed values: `tiktok_us`TikTok US`amazon_us`Amazon US`dtc_us`Your own store`meta_ads`Meta Ads`google_ads`Google Ads`tiktok_ads`TikTok Ads
vertical	enum	Category used to check the voiceover.Allowed values: `general`General`beauty`Beauty & personal care`health`Health & wellness`supplement`Dietary supplements`weight_loss`Weight loss`baby`Baby & kids`apparel`Apparel & textiles`jewelry`Jewelry`home`Home & cleaning`pet`Pet
riskLevel	enum	Top-level verdict (visuals + audio).Allowed values: `PASSREVIEWREJECT`
labels	array<string>	Overall risk labels.
frames	array<object>	Visual findings, with timestamps in seconds.
└timeSeconds	number	Timestamp of the flagged frame in the video, in seconds.
└riskLevel	enum	Risk level of this frame.Allowed values: `PASSREVIEWREJECT`
└description	string	Description of the finding.
└imageUrl	object	Screenshot URL of the flagged frame. This is a short-lived signed URL and will expire; to keep it long term, copy the file to your own storage.
└ocrText	object	Text recognized in the frame.
audios	array<object>	Audio findings, with start and end times in seconds.
└startSeconds	number	Start of the flagged segment, in seconds.
└endSeconds	number	End of the flagged segment, in seconds.
└riskLevel	enum	Risk level of this segment.Allowed values: `PASSREVIEWREJECT`
└description	string	Description of the finding.
└text	object	Transcribed speech of the flagged segment.
transcript	object	Full transcript of the voiceover.
transcriptStatus	object	Voiceover transcription status: `null` = not enabled \| `processing` = transcribing \| `completed` \| `failed` \| `empty` = no audio track. While it is processing, voiceover risks are not yet complete; keep polling.
transcriptRisks	array<object>	Voiceover violations. They are checked by the same engine as text checks and count toward the verdict on an equal footing with visual and audio findings.
└matchedText	string	The matched snippet of the voiceover.
└severity	enum	Severity.Allowed values: `high`High`medium`Medium`low`Low
└category	object	Risk category, localized.
└suggestion	object	Suggested fix, localized.
└legalRef	object	Legal reference, returned in the explainLocale language (citations are identical in both languages).
└replacement	object	Compliant wording that can directly replace matchedText; empty means the snippet can only be removed.
└startSeconds	number	Start of the sentence containing the match, in seconds. You can use it directly to seek.
└endSeconds	number	End of the sentence containing the match, in seconds.
└sentence	object	The full sentence containing the match, for context.
└source	enum	Source of the finding.Allowed values: `rulemodelcustom`
createdAt	object	Creation time.
updatedAt	object	Last update time.

Possible errors

404The record does not exist or belongs to another site

Example

bash

curl "https://www.byerisk.com/api/v1/intl/us/video/checks/{id}" \
  -H "Authorization: Bearer $BYERISK_API_KEY"

json — response

{
  "success": true,
  "data": {
    "id": "string",
    "object": "intl_video_check",
    "status": "processing",
    "video": {
      "url": "string",
      "title": "string",
      "sizeMb": null,
      "durationSeconds": null,
      "width": null,
      "height": null
    },
    "platform": "tiktok_us",
    "vertical": "general",
    "riskLevel": "PASS",
    "labels": [
      "string"
    ],
    "frames": [
      {
        "timeSeconds": 12,
        "riskLevel": "PASS",
        "description": "string",
        "imageUrl": null,
        "ocrText": null
      }
    ],
    "audios": [
      {
        "startSeconds": 0,
        "endSeconds": 0,
        "riskLevel": "PASS",
        "description": "string",
        "text": null
      }
    ],
    "transcript": null,
    "transcriptStatus": null,
    "transcriptRisks": [
      {
        "matchedText": "string",
        "severity": "high",
        "category": null,
        "suggestion": null,
        "legalRef": null,
        "replacement": null,
        "startSeconds": 0,
        "endSeconds": 0,
        "sentence": null,
        "source": "rule"
      }
    ],
    "createdAt": null,
    "updatedAt": null
  }
}

DELETE/v1/intl/us/video/checks/{id}

Delete a video check

Soft-deletes the check and asynchronously removes the uploaded video file.

Path parameters

Field	Type	Description
idRequired	string

Response200

Field	Type	Description
id	string	ID of the deleted record.
object	string	Object type.
deleted	boolean	Always true.

Possible errors

404The record does not exist or belongs to another site

Example

bash

curl -X DELETE https://www.byerisk.com/api/v1/intl/us/video/checks/{id} \
  -H "Authorization: Bearer $BYERISK_API_KEY"

json — response

{
  "success": true,
  "data": {
    "id": "string",
    "object": "intl_text_check",
    "deleted": true
  }
}

Batch checks

POST/v1/intl/us/batches

Submit a batch check

Submits multiple text items, images, and videos in a single request, checks them together, and aggregates the verdict. Limits: up to 10 text items, 20 images, and 10 videos, with no more than 40 items per batch in total.

Returns an ID immediately; the items are checked in parallel in the background. Poll GET {id} for progress: progress.done / progress.total shows how far the batch has progressed, and once all items are complete, result gives the verdict for the whole batch (PASS / REJECT). Each item includes a checkId, which you can pass to the corresponding single-item endpoint to get the full details.

Billing: each item is billed at its own unit price (text per item, images per image, videos per second). If your balance is insufficient, the entire batch is rejected at submission.

Request body

Field	Type	Description
nameRequired	string	Batch name, 1–60 characters.
platformRequired	enum	Publishing platform, applied to the whole batch.Allowed values: `tiktok_us`TikTok US`amazon_us`Amazon US`dtc_us`Your own store`meta_ads`Meta Ads`google_ads`Google Ads`tiktok_ads`TikTok Ads
verticalRequired	enum	Content category, applied to the whole batch.Allowed values: `general`General`beauty`Beauty & personal care`health`Health & wellness`supplement`Dietary supplements`weight_loss`Weight loss`baby`Baby & kids`apparel`Apparel & textiles`jewelry`Jewelry`home`Home & cleaning`pet`Pet
texts	array<string>	Text items, up to 10. Items shorter than 10 characters are dropped instead of failing the whole batch. Rejecting a submission of ten items because one of them is too short, with an error message that cannot say which one, would not be a good contract.
images	array<object>	Image items, up to 20.
└urlRequired	string	Image URL, publicly accessible.
└nameRequired	string	Image title / file name.
└sizeRequired	number	Image size in bytes.
└width	number	Width in pixels.
└height	number	Height in pixels.
videos	array<object>	Video items, up to 10.
└urlRequired	string	Video URL, publicly accessible.
└nameRequired	string	Video title / file name.
└sizeRequired	number	Video size in MB (the same unit as for single video checks, not bytes).
└durationRequired	number	Video duration in seconds. Billing is based on this value.
└width	number	Width in pixels.
└height	number	Height in pixels.
explainLocale	enum	Language in which risk explanations are returned.Allowed values: `zh-CN`Chinese (Simplified)`en-US`EnglishDefault `zh-CN`

Response201

Field	Type	Description
id	string	ID of this check, used to poll for the result.
object	string	Object type.
status	string	Current status. It is processing immediately after submission.

Possible errors

400The batch is empty or exceeds the per-batch item limit

402Insufficient credits to cover the cost of the whole batch

403Batch checks require a Premium plan or higher

Example

bash

curl -X POST https://www.byerisk.com/api/v1/intl/us/batches \
  -H "Authorization: Bearer $BYERISK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Holiday campaign · batch 1",
    "platform": "tiktok_us",
    "vertical": "supplement",
    "texts": [
      "string"
    ],
    "images": [
      {
        "url": "string",
        "name": "string",
        "size": 254112,
        "width": 0,
        "height": 0
      }
    ],
    "videos": [
      {
        "url": "string",
        "name": "string",
        "size": 12.4,
        "duration": 45,
        "width": 0,
        "height": 0
      }
    ],
    "explainLocale": "zh-CN"
  }'

json — response

{
  "success": true,
  "data": {
    "id": "cms8xhc5x0006sp59vrks7zkf",
    "object": "intl_text_check",
    "status": "processing"
  }
}

GET/v1/intl/us/batches

List batches

Returns a paginated list sorted by creation time, newest first, including each batch's progress and verdict. The call also advances the status of a small number of in-progress batches.

Query parameters

Field	Type	Description
page	string	Page number, starting at 1.Default `1`
pageSize	string	Number of items per page, up to 50.Default `20`
explainLocale	enum	Language in which risk explanations are returned (listing also advances item status, so results may be stored during this call).Allowed values: `zh-CN`Chinese (Simplified)`en-US`EnglishDefault `zh-CN`

Response200

Field	Type	Description
object	string	Object type. Always list.
page	number	Current page number.
pageSize	number	Number of items per page.
total	number	Total number of matching items.
hasMore	boolean	Whether there is another page.
data	array<object>	Items on this page.
└id	string	Batch ID.
└object	string	Object type.
└name	string	Batch name.
└status	string	Batch status.
└counts	object	Number of items of each type.
└texts	number	Number of text items.
└images	number	Number of image items.
└videos	number	Number of video items.
└progress	object	Progress.
└total	number	Total number of items.
└done	number	Number of completed items.
└percent	number	Completion percentage (0–100).
└result	object	Batch verdict.
└summary	object	Batch counts.
└violation	number	Number of violations.
└sceneHint	number	Number of scene hints.
└createdAt	object	Creation time.
└finishedAt	object	Completion time.

Example

bash

curl "https://www.byerisk.com/api/v1/intl/us/batches" \
  -H "Authorization: Bearer $BYERISK_API_KEY"

json — response

{
  "success": true,
  "data": {
    "object": "list",
    "page": 1,
    "pageSize": 20,
    "total": 128,
    "hasMore": true,
    "data": [
      {
        "id": "string",
        "object": "intl_batch",
        "name": "string",
        "status": "string",
        "counts": {
          "texts": 0,
          "images": 0,
          "videos": 0
        },
        "progress": {
          "total": 12,
          "done": 9,
          "percent": 75
        },
        "result": null,
        "summary": {
          "violation": 0,
          "sceneHint": 0
        },
        "createdAt": null,
        "finishedAt": null
      }
    ]
  }
}

GET/v1/intl/us/batches/{id}

Get batch progress and results

Each call also triggers one refresh of item status, so you can poll this endpoint directly. Use items[].checkId to get the full details of an individual item.

Path parameters

Field	Type	Description
idRequired	string

Query parameters

Field	Type	Description
explainLocale	enum	Language in which risk explanations are returned. Defaults to zh-CN if omitted.Allowed values: `zh-CN`Chinese (Simplified)`en-US`EnglishDefault `zh-CN`

Response200

Field	Type	Description
id	string	Batch ID.
object	string	Object type.
name	string	Batch name.
platform	enum	Publishing platform.Allowed values: `tiktok_us`TikTok US`amazon_us`Amazon US`dtc_us`Your own store`meta_ads`Meta Ads`google_ads`Google Ads`tiktok_ads`TikTok Ads
vertical	enum	Content category.Allowed values: `general`General`beauty`Beauty & personal care`health`Health & wellness`supplement`Dietary supplements`weight_loss`Weight loss`baby`Baby & kids`apparel`Apparel & textiles`jewelry`Jewelry`home`Home & cleaning`pet`Pet
status	enum	Batch status.Allowed values: `processing`Processing`completed`Completed`failed`Failed
progress	object	Progress.
└total	number	Total number of items.
└done	number	Number of completed items.
└percent	number	Completion percentage (0–100).
result	enum	Batch verdict. Populated only after all items are complete.Allowed values: `PASSREJECT`
summary	object	Batch counts.
└violation	number	Number of violations.
└sceneHint	number	Number of scene hints.
items	array<object>	Item details.
└id	string	Item ID (not the check ID).
└kind	enum	Item type. Note that the value is `text`, not the internal name script, which matches the paths of the single-item endpoints.Allowed values: `textimagevideo`
└checkId	string	The corresponding single-item check ID. Use it with `/text\|image\|video/checks/{id}` to get the full details.
└index	number	Index of the item in the order it was submitted.
└status	enum	Item status.Allowed values: `processing`Processing`completed`Completed`failed`Failed
└riskLevel	object	Item verdict. safe/low/medium/high for text; PASS/REVIEW/REJECT for images and videos.
└summary	object	Item counts.
└violation	number	Number of violations.
└sceneHint	number	Number of scene hints.
└text	string	Text item: the original text.
└riskCount	number	Text item: number of risks.
└image	object	Image item: URL and title.
└video	object	Video item: URL, title, and duration.
└labels	array<string>	Image / video item: risk labels.
└transcriptStatus	object	Video item: voiceover transcription status.
createdAt	object	Creation time.
finishedAt	object	Completion time.

Possible errors

404The batch does not exist or belongs to another site

Example

bash

curl "https://www.byerisk.com/api/v1/intl/us/batches/{id}" \
  -H "Authorization: Bearer $BYERISK_API_KEY"

json — response

{
  "success": true,
  "data": {
    "id": "string",
    "object": "intl_batch",
    "name": "string",
    "platform": "tiktok_us",
    "vertical": "general",
    "status": "processing",
    "progress": {
      "total": 12,
      "done": 9,
      "percent": 75
    },
    "result": "PASS",
    "summary": {
      "violation": 0,
      "sceneHint": 0
    },
    "items": [
      {
        "id": "string",
        "kind": "text",
        "checkId": "string",
        "index": 0,
        "status": "processing",
        "riskLevel": null,
        "summary": {
          "violation": 0,
          "sceneHint": 0
        },
        "text": "string",
        "riskCount": 0,
        "image": null,
        "video": null,
        "labels": [
          "string"
        ],
        "transcriptStatus": null
      }
    ],
    "createdAt": null,
    "finishedAt": null
  }
}

DELETE/v1/intl/us/batches/{id}

Delete a batch

Soft-deletes the batch and all of its item checks, and asynchronously removes the uploaded image / video files.

Path parameters

Field	Type	Description
idRequired	string

Response200

Field	Type	Description
id	string	ID of the deleted record.
object	string	Object type.
deleted	boolean	Always true.

Possible errors

404The batch does not exist or belongs to another site

Example

bash

curl -X DELETE https://www.byerisk.com/api/v1/intl/us/batches/{id} \
  -H "Authorization: Bearer $BYERISK_API_KEY"

json — response

{
  "success": true,
  "data": {
    "id": "string",
    "object": "intl_text_check",
    "deleted": true
  }
}

Custom rules

POST/v1/intl/us/custom-rules

Create a custom rule

Request body

Field	Type	Description
keywordRequired	string	The term to check for. On the US site, enter English terms: the text checked is English, so Chinese terms never match. (length 0–100)
matchType	enum	How the term is matched: keyword = substring match (default; a match anywhere counts), phrase = word-boundary match. For space-delimited languages such as English, use phrase: substring matching lets a short term hit longer words (for example, cure matches secure).Allowed values: `keyword`Substring match`phrase`Word-boundary matchDefault `keyword`
replacement	string	Replacement. When set, matches include `replacement`, which you can use for an exact one-click replacement; leave it empty to flag only. (length 0–100)
note	string	Note, visible only to you. (length 0–200)
enabled	boolean	Whether the rule is enabled. A disabled rule is kept but not applied during checks.Default `true`

Response201

Field	Type	Description
id	string	Rule ID.
object	string	Object type.
keyword	string	The term to check for.
matchType	enum	Match type.Allowed values: `keyword`Substring match`phrase`Word-boundary match
replacement	object	Replacement. If empty, matches are flagged only.
note	object	Note, visible only to you.
enabled	boolean	Whether the rule is enabled.
createdAt	object	Creation time.
updatedAt	object	Last update time.

Possible errors

400The term already exists on this site, or your plan's word list limit has been reached

403Custom rules are a paid feature and are not available on your current plan

Example

bash

curl -X POST https://www.byerisk.com/api/v1/intl/us/custom-rules \
  -H "Authorization: Bearer $BYERISK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "money-back guarantee",
    "matchType": "keyword",
    "replacement": "30-day return policy applies",
    "note": "string",
    "enabled": false
  }'

json — response

{
  "success": true,
  "data": {
    "id": "string",
    "object": "intl_custom_rule",
    "keyword": "money-back guarantee",
    "matchType": "keyword",
    "replacement": null,
    "note": null,
    "enabled": false,
    "createdAt": null,
    "updatedAt": null
  }
}

GET/v1/intl/us/custom-rules

List all custom rules on this site

Sorted by creation time, newest first, with no pagination. Only terms on this site are returned: the same term is stored as a separate entry on each site, and an entry on one site never produces matches on another.

Response200

Field	Type	Description
object	string	Object type. Always list.
data	array<object>	All rules on this site (word lists are small, so results are not paginated).
└id	string	Rule ID.
└object	string	Object type.
└keyword	string	The term to check for.
└matchType	enum	Match type.Allowed values: `keyword`Substring match`phrase`Word-boundary match
└replacement	object	Replacement. If empty, matches are flagged only.
└note	object	Note, visible only to you.
└enabled	boolean	Whether the rule is enabled.
└createdAt	object	Creation time.
└updatedAt	object	Last update time.
total	number	Total number of rules.

Example

bash

curl "https://www.byerisk.com/api/v1/intl/us/custom-rules" \
  -H "Authorization: Bearer $BYERISK_API_KEY"

json — response

{
  "success": true,
  "data": {
    "object": "list",
    "data": [
      {
        "id": "string",
        "object": "intl_custom_rule",
        "keyword": "money-back guarantee",
        "matchType": "keyword",
        "replacement": null,
        "note": null,
        "enabled": false,
        "createdAt": null,
        "updatedAt": null
      }
    ],
    "total": 0
  }
}

PATCH/v1/intl/us/custom-rules/{id}

Update a custom rule

Updates only the fields you provide.

Path parameters

Field	Type	Description
idRequired	string

Request body

Field	Type	Description
keyword	string	The term to check for. (length 0–100)
replacement	string	Replacement. (length 0–100)
note	string	Note. (length 0–200)
enabled	boolean	Whether the rule is enabled.

Response200

Field	Type	Description
id	string	Rule ID.
object	string	Object type.
keyword	string	The term to check for.
matchType	enum	Match type.Allowed values: `keyword`Substring match`phrase`Word-boundary match
replacement	object	Replacement. If empty, matches are flagged only.
note	object	Note, visible only to you.
enabled	boolean	Whether the rule is enabled.
createdAt	object	Creation time.
updatedAt	object	Last update time.

Possible errors

404The rule does not exist or belongs to another site

Example

bash

curl -X PATCH https://www.byerisk.com/api/v1/intl/us/custom-rules/{id} \
  -H "Authorization: Bearer $BYERISK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "string",
    "replacement": "string",
    "note": "string",
    "enabled": false
  }'

json — response

{
  "success": true,
  "data": {
    "id": "string",
    "object": "intl_custom_rule",
    "keyword": "money-back guarantee",
    "matchType": "keyword",
    "replacement": null,
    "note": null,
    "enabled": false,
    "createdAt": null,
    "updatedAt": null
  }
}

DELETE/v1/intl/us/custom-rules/{id}

Delete a custom rule

Permanently deletes the rule. This action cannot be undone.

Path parameters

Field	Type	Description
idRequired	string

Response200

Field	Type	Description
id	string	ID of the deleted record.
object	string	Object type.
deleted	boolean	Always true.

Possible errors

404The rule does not exist or belongs to another site

Example

bash

curl -X DELETE https://www.byerisk.com/api/v1/intl/us/custom-rules/{id} \
  -H "Authorization: Bearer $BYERISK_API_KEY"

json — response

{
  "success": true,
  "data": {
    "id": "string",
    "object": "intl_text_check",
    "deleted": true
  }
}

POST/v1/intl/us/custom-rules/bulk-import

Import custom rules in bulk

Up to 2000 terms per request. Idempotency-friendly: duplicates within the request and terms already in your word list are skipped instead of causing an error, and the response reports three separate counts: imported / skippedDuplicate / rejectedQuota. Terms beyond your quota are rejected; accepted terms are still written as usual.

Request body

Field	Type	Description
itemsRequired	array<object>	Terms to import, up to 2000 per request. Duplicates within the request and terms already in your word list are skipped automatically (each counted separately in the response) without causing an error.
└keywordRequired	string	The term to check for. (length 0–100)
└replacement	string	Replacement. (length 0–100)
└note	string	Note. (length 0–200)

Response201

Field	Type	Description
object	string	Object type.
total	number	Total number of terms submitted in this request.
imported	number	Number of terms actually written.
skippedDuplicate	number	Number of terms skipped because they were duplicated within the request or already exist in your word list.
rejectedQuota	number	Number of terms rejected because they exceeded your plan's quota.

Possible errors

403Custom rules are a paid feature and are not available on your current plan

Example

bash

curl -X POST https://www.byerisk.com/api/v1/intl/us/custom-rules/bulk-import \
  -H "Authorization: Bearer $BYERISK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "keyword": "string",
        "replacement": "string",
        "note": "string"
      }
    ]
  }'

json — response

{
  "success": true,
  "data": {
    "object": "intl_custom_rule_import_result",
    "total": 0,
    "imported": 0,
    "skippedDuplicate": 0,
    "rejectedQuota": 0
  }
}

GET/v1/intl/us/custom-rules/quota

Get word list quota

Returns the number of terms used and your plan's limit. ⚠️ **used is account-wide** (it includes terms you added on other sites), whereas isPaid is the subscription status of this site: plans are isolated by site, but word list quota is not.

Response200

Field	Type	Description
object	string	Object type.
used	number	Number of terms used. The quota is account-wide and shared across sites; it includes terms you added on other sites.
limit	number	Word list limit for your current plan. 0 on the Basic plan.
isPaid	boolean	Whether this site currently has a paid subscription.

Example

bash

curl "https://www.byerisk.com/api/v1/intl/us/custom-rules/quota" \
  -H "Authorization: Bearer $BYERISK_API_KEY"

json — response

{
  "success": true,
  "data": {
    "object": "intl_custom_rule_quota",
    "used": 12,
    "limit": 500,
    "isPaid": true
  }
}

GET/v1/intl/us/custom-rules/settings

Get the master switch status

When off, no custom terms are applied during checks (your data is kept). The switch is account-wide and is not set per site.

Response200

Field	Type	Description
object	string	Object type.
enabled	boolean	Account-wide master switch. When off, no custom terms are applied during checks (your data is kept).

Example

bash

curl "https://www.byerisk.com/api/v1/intl/us/custom-rules/settings" \
  -H "Authorization: Bearer $BYERISK_API_KEY"

json — response

{
  "success": true,
  "data": {
    "object": "intl_custom_rule_settings",
    "enabled": false
  }
}

PATCH/v1/intl/us/custom-rules/settings

Update the master switch

Independent of each rule's own enabled flag: when the master switch is off, per-rule enabled settings have no effect.

Request body

Field	Type	Description
enabledRequired	boolean	Tenant-level master switch. When off, no custom terms are applied during checks (your data is kept). It is independent of each rule's enabled flag. The switch itself is not set per country site: it answers the question "does this account use a custom word list?"

Response200

Field	Type	Description
object	string	Object type.
enabled	boolean	Account-wide master switch. When off, no custom terms are applied during checks (your data is kept).

Possible errors

403Custom rules are a paid feature and are not available on your current plan

Example

bash

curl -X PATCH https://www.byerisk.com/api/v1/intl/us/custom-rules/settings \
  -H "Authorization: Bearer $BYERISK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'

json — response

{
  "success": true,
  "data": {
    "object": "intl_custom_rule_settings",
    "enabled": false
  }
}

Account

GET/v1/intl/us/account

Get account balance and usage

Returns the credit balance, plan, and this month's call counts for each check type on this site.

⚠️ Credits and subscriptions are isolated by site: the balance here does not include credits you hold on other sites, and vice versa. We recommend calling this endpoint once before you integrate to confirm your balance; otherwise, the only way to find out that your balance is insufficient is to run into a 402.

Usage counts include all entry points (web and API), not only API calls.

Response200

Field	Type	Description
object	string	Object type.
country	string	The site this call belongs to.
credits	object	Credit balance for this site. Credits are isolated by site; your balance on the ByeRisk China site is not included here.
└total	number	Total available credits on this site.
└subscription	number	Credits granted by your plan.
└activity	number	Credits granted through promotions.
└booster	number	Credits from credit packs.
└expiringSoon	object	Credits that expire within 7 days; null if there are none.
subscription	object	Plan on this site.
usageThisMonth	object	Number of checks of each type on this site in the current calendar month, across all entry points, including web and API.

Example

bash

curl "https://www.byerisk.com/api/v1/intl/us/account" \
  -H "Authorization: Bearer $BYERISK_API_KEY"

json — response

{
  "success": true,
  "data": {
    "object": "intl_account",
    "country": "us",
    "credits": {
      "total": 8420,
      "subscription": 0,
      "activity": 0,
      "booster": 0,
      "expiringSoon": null
    },
    "subscription": null,
    "usageThisMonth": null
  }
}

Uploads

POST/v1/intl/us/uploads/policy

Get direct-upload credentials

You need this endpoint only if you do not have publicly accessible storage for your assets. If your assets are already in your own object storage or on a CDN, put the URL directly into the check endpoint and skip this step.

Returns POST Policy direct-upload credentials for a standard form upload:

bash

curl -X POST "$host" \
  -F "key=$dir<your-filename>" \
  -F "policy=$policy" \
  -F "OSSAccessKeyId=$accessKeyId" \
  -F "signature=$signature" \
  -F "file=@./promo-01.mp4"

After a successful upload, the asset URL is {cdnHost}/{key}; put it in the videoUrl / imageUrl field of the check endpoint. The credentials expire after 5 minutes and allow writes only to the directory prefix dedicated to your account on this site.

Request body

Field	Type	Description
kindRequired	enum	Asset type, which determines the size limit: video up to 1GB, image up to 10MB.Allowed values: `videoimage`

Response201

Field	Type	Description
object	string	Object type.
kind	enum	Asset type.Allowed values: `videoimage`
host	string	Target URL for the direct upload (POST the form here).
cdnHost	string	Host from which the asset is served after a successful upload. Asset URL = `{cdnHost}/{key}`.
dir	string	Directory prefix you are allowed to write to. key must start with it, or the upload is rejected.
policy	string	Upload policy (base64).
accessKeyId	string	AccessKeyId for the direct upload.
signature	string	Policy signature.
maxSizeBytes	number	Size limit for this type, in bytes.
expiresAt	string	Credential expiration time (ISO 8601). The credentials expire 5 minutes after issue.

Example

bash

curl -X POST https://www.byerisk.com/api/v1/intl/us/uploads/policy \
  -H "Authorization: Bearer $BYERISK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "video"
  }'

json — response

{
  "success": true,
  "data": {
    "object": "intl_upload_policy",
    "kind": "video",
    "host": "string",
    "cdnHost": "string",
    "dir": "string",
    "policy": "string",
    "accessKeyId": "string",
    "signature": "string",
    "maxSizeBytes": 0,
    "expiresAt": "string"
  }
}