> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bringits.com/llms.txt
> Use this file to discover all available pages before exploring further.

# LLM Scraping API

> Send a ChatGPT prompt through the LLM Scraping API

The **POST /llm** endpoint sends a ChatGPT prompt through the LLM Scraping API. You send `prompt` and optional `countries`.

**Access token:** Generate your access token from the Bringits platform. Send it as a Bearer token on every call and in **Try it**.

## Endpoint

`https://unblocker.bringits.com/llm`

## Headers

In **Try it**, enter your JWT only in **Authorize** (token field). Do not paste the full `Authorization` header or duplicate the token in a Headers box.

| Header            | Sent as                 | Required | Notes                                                                                                                                |
| ----------------- | ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Content-Type**  | `application/json`      | Yes      | Request body must be JSON.                                                                                                           |
| **Authorization** | `Bearer <access_token>` | Yes      | Production gateway validates the JWT and injects **`x-tenant-id`** from the `tenantId` claim. You do not set `x-tenant-id` yourself. |

### Response headers

| Header           | When           | Description                      |
| ---------------- | -------------- | -------------------------------- |
| **x-request-id** | Every response | Include when contacting support. |

Rate-limit headers (`X-RateLimit-*`, `Retry-After`) are currently returned on **[POST /request](/unblocker/request)** 429 responses, not on `/llm`.

## Request body parameters

| Parameter     | Type      | Description                                                                                                          | Required |
| ------------- | --------- | -------------------------------------------------------------------------------------------------------------------- | -------- |
| **prompt**    | string    | The question to send. Must be non-empty after trimming.                                                              | Yes      |
| **source**    | string    | LLM to query. Options: ChatGPT, Gemini (coming soon). Defaults to ChatGPT if omitted.                                | No       |
| **countries** | string\[] | Optional ISO country codes (e.g. `["US"]`). The answer is fetched from that region. Defaults to `["US"]` if omitted. | No       |

## How the request is handled

1. **Quota** — Your monthly allowance is checked before the call.
2. **Location** — When you send `countries`, the answer is fetched from that region. Omit `countries` and the call uses `["US"]`.
3. **Fresh request** — Each call is independent; there is no session to reuse from a previous call.
4. **Answer** — On success you receive the answer as JSON (`response.text` and `response.markdown`).

## Response format

When the call succeeds, the HTTP status is **200** and the body is:

```json theme={null}
{
  "id": "llm_A1B2C3D4E5F6",
  "source": "chatgpt",
  "model": null,
  "response": {
    "text": "4",
    "markdown": "4"
  },
  "metadata": {
    "country": "US"
  }
}
```

| Field                 | Type   | Description                                                       |
| --------------------- | ------ | ----------------------------------------------------------------- |
| **id**                | string | Request id (`llm_` plus 12 uppercase hex characters from a UUID). |
| **source**            | string | `"chatgpt"`.                                                      |
| **model**             | null   | Reserved; ChatGPT does not expose a model id.                     |
| **response.text**     | string | Plain-text answer.                                                |
| **response.markdown** | string | Markdown answer (same as text when no markdown).                  |
| **metadata.country**  | string | Country used for the call.                                        |

## When a request fails

If the call does not succeed, the HTTP status is not **200** and the body is:

```json theme={null}
{
  "status": null,
  "headers": {},
  "body": null,
  "error": "REQUEST_FAILED"
}
```

Treat any non-200 response as a failed call with `"error": "REQUEST_FAILED"`. Use the HTTP status to decide next steps:

* **400**, **401**, **403**, **404**, **422** — fix the prompt, JSON, token, or route. Do not retry the same request.
* **429**, **502**, **503**, and other non-200 server-side statuses — retry later with exponential backoff (for example 1s, 2s, 4s) and stop after a few attempts. `/llm` does not return `Retry-After` on 429.

Include **`x-request-id`** from the response headers when you contact support.

## Usage example

```bash theme={null}
curl -si https://unblocker.bringits.com/llm \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -d '{"prompt":"What is the best proxy provider?","countries":["US"]}'
```

On success, read `response.text` (and `response.markdown`) from the JSON body.

## Best practices

* **Store the token in a secret** instead of hardcoding.
* **Success vs failure:** HTTP **200** means you got an answer in `response.text`. Any other status means the call failed with `"error": "REQUEST_FAILED"`.
* **Retries:** Retry only transient failures (**429**, **502**, **503**, and similar). Do not retry **400**, **401**, **403**, **404**, or **422** with the same payload. For repeated failures, contact support with **`x-request-id`**.

## Related

* [Overview](/unblocker) – Token acquisition
* [Request](/unblocker/request) – HTTP and browser requests (`method` + `url`)

## Try it

Use the interactive **Try it** panel to send a real request.

### Before you start

1. **Get a token** – Generate your access token from the Bringits platform.
2. **Authenticate** – Enter the token in **Authorize** (Bearer is applied automatically).
3. **Edit the body** – Default: `{"prompt":"...","countries":["US"]}`.
4. **Send** – Success: `response.text` on the LLM object.

<Note>
  **Security:** Do not share your token or commit it to code. Use the Authorize
  dialog only in your browser; the token is not stored in the documentation.
</Note>


## OpenAPI

````yaml POST /llm
openapi: 3.0.3
info:
  title: Unblocker API
  description: >-
    Public API for Unblocker: forward HTTP or browser-rendered requests with
    POST /request, or send a ChatGPT prompt with the LLM Scraping API (POST
    /llm). Use **Authorize** to set your Bearer token, then **Try it** to send a
    live request.
  version: 1.4.0
servers:
  - url: https://unblocker.bringits.com
    description: Unblocker Server
security:
  - bearerAuth: []
tags:
  - name: Request
    description: Unblocker scrape (`POST /request`)
  - name: LLM
    description: LLM Scraping API (`POST /llm`)
paths:
  /llm:
    post:
      tags:
        - LLM
      summary: ChatGPT prompt (LLM Scraping API)
      description: >-
        Sends a prompt to ChatGPT through the LLM Scraping API. You send
        `prompt` and optional `countries`. When you send `countries`, the
        request is routed through that location. Success returns the LLM object
        (`response.text`). Use **Authorize** to enter your Bearer token, then
        **Try it**.
      operationId: postLlm
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LlmRequest'
            examples:
              chatgpt:
                summary: ChatGPT prompt
                value:
                  prompt: What is the best proxy provider?
                  countries:
                    - US
      responses:
        '200':
          description: >-
            ChatGPT answer. Outer HTTP 200 with the Bringits LLM object
            (`response.text`).
          headers:
            x-request-id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatgptSuccessResponse'
              examples:
                chatgpt:
                  summary: ChatGPT answer
                  value:
                    id: llm_A1B2C3D4E5F6
                    source: chatgpt
                    model: null
                    response:
                      text: '4'
                      markdown: '4'
                    metadata:
                      country: US
        '400':
          $ref: '#/components/responses/LlmRequestFailed'
        '401':
          $ref: '#/components/responses/LlmRequestFailed'
        '403':
          $ref: '#/components/responses/LlmRequestFailed'
        '404':
          $ref: '#/components/responses/LlmRequestFailed'
        '422':
          $ref: '#/components/responses/LlmRequestFailed'
        '429':
          $ref: '#/components/responses/LlmRequestFailed'
        '502':
          $ref: '#/components/responses/LlmRequestFailed'
        '503':
          $ref: '#/components/responses/LlmRequestFailed'
        default:
          $ref: '#/components/responses/LlmRequestFailed'
components:
  schemas:
    LlmRequest:
      type: object
      required:
        - prompt
      properties:
        prompt:
          type: string
          minLength: 1
          pattern: .*\S.*
          description: Question to send to ChatGPT. Must be non-empty after trimming.
          example: What is the best proxy provider?
        source:
          type: string
          enum:
            - chatgpt
          default: chatgpt
          description: >-
            LLM to query. Options: ChatGPT, Gemini (coming soon). Defaults to
            ChatGPT if omitted.
          example: chatgpt
        countries:
          type: array
          items:
            type: string
          description: >-
            Optional ISO country codes. When set, the request is routed through
            that location. Defaults to ["US"] if omitted.
          example:
            - US
    ChatgptSuccessResponse:
      type: object
      required:
        - id
        - source
        - model
        - response
        - metadata
      properties:
        id:
          type: string
          pattern: ^llm_[0-9A-F]{12}$
          description: Request id (`llm_` plus 12 uppercase hex characters from a UUID).
          example: llm_A1B2C3D4E5F6
        source:
          type: string
          enum:
            - chatgpt
        model:
          type: string
          nullable: true
          description: Reserved. ChatGPT does not expose a model id.
          example: null
        response:
          type: object
          required:
            - text
            - markdown
          properties:
            text:
              type: string
              description: Plain-text answer.
            markdown:
              type: string
              description: Markdown answer (same as text when no markdown is present).
        metadata:
          type: object
          required:
            - country
          properties:
            country:
              type: string
              description: Country used for the call.
              example: US
    LlmFailureEnvelope:
      type: object
      required:
        - status
        - headers
        - body
        - error
      properties:
        status:
          nullable: true
          enum:
            - null
          example: null
        headers:
          type: object
          additionalProperties:
            type: string
          example: {}
        body:
          nullable: true
          enum:
            - null
          example: null
        error:
          type: string
          description: Always REQUEST_FAILED for POST /llm failures.
          enum:
            - REQUEST_FAILED
          example: REQUEST_FAILED
  headers:
    XRequestId:
      description: >-
        Unique ID for this request. Present on every POST /llm response. Include
        it when contacting support.
      schema:
        type: string
        format: uuid
  responses:
    LlmRequestFailed:
      description: >-
        The request failed. The body always contains `"error":
        "REQUEST_FAILED"`.
      headers:
        x-request-id:
          $ref: '#/components/headers/XRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/LlmFailureEnvelope'
          examples:
            requestFailed:
              value:
                status: null
                headers: {}
                body: null
                error: REQUEST_FAILED
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Use **Authorize** and enter your tenant JWT in the token field only. The
        gateway validates the token and injects `x-tenant-id` from the
        `tenantId` claim; do not set `x-tenant-id` manually in production.

````