> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://api-docs.botbye.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://api-docs.botbye.com/_mcp/server. # report POST https://api.botbye.com/api/v1/{account_id}/projects/{project_id}/challenges/reports Content-Type: application/json # Report a Challenge Result Tells BotBye how a challenge one of your users was given was answered — by your own MFA, by a captcha you run yourself, by ours solved out of band, or by a person in your support team. A `PASSED` report may carry a **grant**, which makes the next requests of that user answer `ALLOW` where they would have answered `CHALLENGE`. A grant never lifts a `BLOCK`: a request we consider malicious is declined whatever a report said. A `FAILED` report withdraws any grant standing on either identity it names, and may not carry one. ## Endpoint ``` POST {base_url}/api/v1/{account_id}/projects/{project_id}/challenges/reports ``` ## Authentication Requires API key authentication: ``` Authorization: Bearer {api_key} ``` ## Path Parameters | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ---------------------------------------- | | `account_id` | string | Yes | Your unique BotBye account identifier | | `project_id` | string | Yes | The project the challenge was issued for | ## Request Body | Field | Type | Required | Description | | ----------------------- | ------- | ------------------- | ------------------------------------------------------------------------------------------------- | | `subject` | object | Yes | Who the report is about | | `subject.visitorId` | string | No | The BotBye visitor id the challenged request carried, up to 256 characters | | `subject.userAccountId` | string | No | Your own account id for the end user, up to 256 characters | | `subject.customFields` | object | No | Up to 5 of your own key/value pairs the granted requests must also carry | | `result` | string | Yes | `PASSED` or `FAILED` | | `channel` | string | Yes | What verified the person: `CAPTCHA`, `MFA`, `EXTERNAL_CAPTCHA` or `MANUAL` | | `grant` | object | No | Present to buy a bypass; omit to file the report alone | | `grant.ttlSeconds` | integer | Yes, within `grant` | How long the bypass lives, 60–86400 | | `grant.maxAttempts` | integer | No, within `grant` | How many requests it releases, at least 1; omit to release every request until the bypass expires | At least one of `subject.visitorId` and `subject.userAccountId` is required: a grant is keyed on one of them, and `customFields` can only narrow that key. A grant keyed on a custom field alone would be claimable by anyone who guessed the value, since custom fields arrive with every request. `subject.visitorId` is only usable on requests that carry a BotBye token, which is where the visitor id can be verified. A report about a backend-only flow should name `subject.userAccountId` instead. ## Response Structure | Field | Type | Description | | ------------------------ | ------- | ---------------------------------------------------------------------------------------------------------------------- | | `reportId` | string | Identifier of the report; also the id of the grant it issued | | `grantExpiresAt` | string | Timestamp (epoch millis) the grant stops applying; absent when the report issued none | | `grantRemainingAttempts` | integer | Requests the grant still releases; absent when the report issued none, and when the grant it issued counts no attempts | ## Use Cases * **Support**: a user cannot pass the captcha and contacts you; report the identity check your agent performed and let their next few requests through. * **Your own MFA**: report a passed multi-factor check so the user is not challenged again straight after it. * **Third-party captcha**: report the result of a captcha you run yourself. > **Accepted permissions** > `Project → Challenges → Action → Report challenge result` > > **Token scope** > `Project Action` Reference: https://api-docs.botbye.com/bot-bye-api/challenges/report ## Authentication - `X-Api-Key` header (required) — Personal access token. Create it in your BotBye account under **Profile → Personal Access Tokens**, tick the scopes the endpoints you call require (see each endpoint's **Token scope**), and send the token in the `X-Api-Key` request header. A token works only for the account it was created in. ## Request ### Path parameters - `account_id` (string, required) - `project_id` (string, required) ### Body (application/json) This endpoint expects an object. - `subject` (object, required) - `visitorId` (string, optional) - `userAccountId` (string, optional) - `customFields` (map from string to string, optional) - `result` (enum, required) - Allowed values: `PASSED`, `FAILED` - `channel` (enum, required) - Allowed values: `CAPTCHA`, `MFA`, `EXTERNAL_CAPTCHA`, `MANUAL` - `grant` (object, optional) - `ttlSeconds` (integer, required) - `maxAttempts` (integer, optional) ## Response ### 200 success - `reportId` (string, required) - `grantExpiresAt` (string, optional) - `grantRemainingAttempts` (integer, optional) ## Errors ### 400 Bad Request Error fail - `message` (string, required) - `code` (string, required) - `type` (string, required) - `context` (any, optional) ## Examples **Request** ```json { "result": "PASSED", "channel": "CAPTCHA" } ``` **Response** ```json { "reportId": "01a09605-624a-7ad0-82c8-8ff8abf8b0d2", "grantExpiresAt": "1789209210168", "grantRemainingAttempts": 2 } ``` **SDK Code** ```python Challenges_report_example import requests url = "https://api.botbye.com/api/v1/account_id/projects/project_id/challenges/reports" payload = { "result": "PASSED", "channel": "CAPTCHA" } headers = { "X-Api-Key": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Challenges_report_example const url = 'https://api.botbye.com/api/v1/account_id/projects/project_id/challenges/reports'; const options = { method: 'POST', headers: {'X-Api-Key': '', 'Content-Type': 'application/json'}, body: '{"result":"PASSED","channel":"CAPTCHA"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Challenges_report_example package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.botbye.com/api/v1/account_id/projects/project_id/challenges/reports" payload := strings.NewReader("{\n \"result\": \"PASSED\",\n \"channel\": \"CAPTCHA\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("X-Api-Key", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Challenges_report_example require 'uri' require 'net/http' url = URI("https://api.botbye.com/api/v1/account_id/projects/project_id/challenges/reports") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["X-Api-Key"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"result\": \"PASSED\",\n \"channel\": \"CAPTCHA\"\n}" response = http.request(request) puts response.read_body ``` ```java Challenges_report_example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.botbye.com/api/v1/account_id/projects/project_id/challenges/reports") .header("X-Api-Key", "") .header("Content-Type", "application/json") .body("{\n \"result\": \"PASSED\",\n \"channel\": \"CAPTCHA\"\n}") .asString(); ``` ```php Challenges_report_example request('POST', 'https://api.botbye.com/api/v1/account_id/projects/project_id/challenges/reports', [ 'body' => '{ "result": "PASSED", "channel": "CAPTCHA" }', 'headers' => [ 'Content-Type' => 'application/json', 'X-Api-Key' => '', ], ]); echo $response->getBody(); ``` ```csharp Challenges_report_example using RestSharp; var client = new RestClient("https://api.botbye.com/api/v1/account_id/projects/project_id/challenges/reports"); var request = new RestRequest(Method.POST); request.AddHeader("X-Api-Key", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"result\": \"PASSED\",\n \"channel\": \"CAPTCHA\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Challenges_report_example import Foundation let headers = [ "X-Api-Key": "", "Content-Type": "application/json" ] let parameters = [ "result": "PASSED", "channel": "CAPTCHA" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.botbye.com/api/v1/account_id/projects/project_id/challenges/reports")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```