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

# Agent

> Give it a task and it searches, reads pages and fills your fields, with a quote for each. Send one request and get JSON back.

Best for a question that needs several pages, like the pricing tiers of a few products or the CEO and headquarters city of a list of startups. Send prompt, and schema for the fields you want (any JSON Schema), and urls to start from. It answers at once with an id, threadId and threadTurn; ask agent.status for the result. The agent searches, reads pages and checks every value against the page text, in up to 3 rounds. It is charged step by step at the normal price of each search and page, plus \$3 per 1,000 pages for each planning or answering step, and stops before maxCredits. A run that cannot finish inside maxCredits fails with stopReason credit\_limit\_reached and what it found in partial; what it spent is still charged. To ask a follow-up, send the threadId from agent.status.

## Price

Each search and page at its normal price, plus $3 per 1,000 pages for each planning or answering step that returns something, up to the limit you set with `maxCredits` ($5 when you leave it out). Starting the run is free.

See [Pricing](https://docs.stophy.dev/account/pricing.md).

```bash cURL theme={null}
curl -X POST https://api.stophy.dev/v1/agent \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"What is the name of the configuration file this page describes?","urls":["https://bun.com/docs/runtime/bunfig"],"schema":{"type":"object","properties":{"file":{"type":"string"}}},"maxCredits":10}'
```

```typescript TypeScript theme={null}
const response = await fetch("https://api.stophy.dev/v1/agent", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    prompt: "What is the name of the configuration file this page describes?",
    urls: ["https://bun.com/docs/runtime/bunfig"],
    schema: { type: "object", properties: { file: { type: "string" } } },
    maxCredits: 10,
  }),
});
console.log(await response.json());
```

```python Python theme={null}
import os

import requests

response = requests.post(
    "https://api.stophy.dev/v1/agent",
    headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
    json={
        "prompt": "What is the name of the configuration file this page describes?",
        "urls": ["https://bun.com/docs/runtime/bunfig"],
        "schema": {
            "type": "object",
            "properties": {"file": {"type": "string"}},
        },
        "maxCredits": 10,
    },
)
print(response.json())
```

```json 200 theme={null}
{
  "success": true,
  "id": "job_4kxytfWzbr774qn3-Ju4Qw",
  "url": "https://api.stophy.dev/v1/agent/job_4kxytfWzbr774qn3-Ju4Qw",
  "threadId": "job_4kxytfWzbr774qn3-Ju4Qw",
  "threadTurn": 1,
  "costUsd": 0,
  "creditsUsed": 0,
  "requestId": "819c366d-5eca-4f8e-b91f-d6181b99951e"
}
```


## OpenAPI

````yaml api-reference/openapi.json POST /v1/agent
openapi: 3.1.0
info:
  title: Stophy API
  version: '1'
  description: >-
    Each operation shows its method and its input: a JSON object body, path and
    query parameters, or a file upload.


    Responses leave out empty values: null, empty strings, empty objects and
    empty nested lists are not sent.


    Text comes back whole. To get shorter responses, add
    ?maxTextLength=<characters> to the URL. Every text value longer than that is
    cut and ends with …. A screenshot is never cut, and a page whose text was
    cut has isTruncated set to true.


    x-cost-usd is what one call costs, in dollars. Every call costs the same,
    whatever it returns, unless an operation's description says it costs per 10
    results, or per hour of audio. Then x-cost-usd is the lowest price and
    x-cost-usd-max the most one call can cost. Where an operation takes limit,
    send it to return fewer results and pay for fewer.


    When a response has a cursor, send it back unchanged with the same input to
    get the next page. When it has a page, send the next page number.
servers:
  - url: https://api.stophy.dev
security:
  - apiKey: []
paths:
  /v1/agent:
    post:
      summary: >-
        Give it a task and it searches, reads pages and fills your fields, with
        a quote for each
      description: >-
        Costs each search and page at its normal price, plus $3 per 1,000 pages
        for each planning or answering step that returns something, never more
        than maxCredits. Each step is charged when it finishes. Starting the run
        is free.
      operationId: agent
      parameters:
        - $ref: '#/components/parameters/MaxTextLength'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                prompt:
                  type: string
                  minLength: 1
                  maxLength: 10000
                  description: >-
                    What to find, in plain words, such as the pricing tiers of
                    Pinecone, Qdrant and Weaviate, or the CEO and headquarters
                    city of each of these startups.
                urls:
                  description: >-
                    Pages to start from, up to 20. An address with * in it, such
                    as https://qdrant.tech/blog/*, is expanded from the site's
                    own page list, up to 10 pages. Without urls the agent
                    searches the web.
                  minItems: 1
                  maxItems: 20
                  type: array
                  items:
                    type: string
                    maxLength: 2048
                schema:
                  description: >-
                    The fields to fill, as a JSON Schema (draft-07 or 2020-12)
                    object with properties. Pydantic's model_json_schema() and
                    zod's toJSONSchema() output work as they are. enum, const,
                    anyOf, oneOf, nullable types, $ref with $defs, required,
                    descriptions and any key names are read. Up to 100 top-level
                    fields and 32 KB. A field the page does not state comes back
                    null.
                  type: object
                  propertyNames:
                    type: string
                  additionalProperties:
                    $ref: '#/components/schemas/agent.input.schema0'
                maxCredits:
                  default: 2500
                  description: >-
                    The most this run may spend, counted in steps of $0.002.
                    Default 2500, which is $5. Every step is checked against
                    what is left before it runs, so the run never goes over. A
                    run that cannot finish inside it fails with stopReason
                    credit_limit_reached and what it found in partial. What it
                    already spent is charged.
                  type: number
                  exclusiveMinimum: 0
                includeSources:
                  default: true
                  description: >-
                    Send false to leave sources out of the answer. They cost
                    nothing.
                  type: boolean
                model:
                  default: stophy
                  description: >-
                    Any model name is accepted. Every name runs the same agent,
                    and the name you send is echoed back.
                  type: string
                  minLength: 1
                  maxLength: 100
                mode:
                  description: >-
                    extract (the default) fills your fields on every turn. chat
                    lets a follow-up that asks for no new data get a short reply
                    in message, for $3 per 1,000 pages, instead of a new run.
                    Needs threadId. A follow-up that omits mode keeps the
                    thread's mode.
                  type: string
                  enum:
                    - extract
                    - chat
                effort:
                  description: >-
                    How many search-and-read rounds the agent may take: low 1,
                    medium 2, high 3 (the default). A follow-up that omits
                    effort keeps the thread's.
                  type: string
                  enum:
                    - low
                    - medium
                    - high
                location:
                  description: >-
                    The country every search and page read goes out from, and
                    results are localized to. A follow-up that omits location
                    keeps the thread's.
                  type: object
                  properties:
                    country:
                      description: Two-letter country code, such as DE or JP.
                      type: string
                      minLength: 2
                      maxLength: 2
                  required:
                    - country
                strictConstrainToURLs:
                  description: >-
                    Send true to read only the pages in urls, with no searching.
                    Needs urls, or a thread that has them.
                  type: boolean
                threadId:
                  description: >-
                    Ask a follow-up in the same thread: send the threadId an
                    earlier run returned. The run sees the earlier question and
                    answer, and omitted urls, schema, effort, mode and location
                    carry over.
                  type: string
                  pattern: ^[A-Za-z0-9_-]{1,100}$
                zeroDataRetention:
                  description: >-
                    Send true to keep nothing from this run: the prompt, steps
                    and result are held for one hour at most and nothing is
                    logged. Each page read adds $2 per 1,000 pages. Cannot be
                    sent with threadId.
                  type: boolean
                safe:
                  description: >-
                    Send true to hide explicit results from every web search in
                    the run. Pages in urls and pages the agent opens are not
                    filtered. A follow-up that omits safe keeps the thread's.
                  type: boolean
                auditMetadata:
                  description: >-
                    Who made the request, kept with the run and read back by
                    agent.status.
                  type: object
                  properties:
                    username:
                      type: string
                      maxLength: 1024
                  required:
                    - username
                  additionalProperties: false
                webhook:
                  description: >-
                    Where to be told about the job: a plain address, or { url }
                    which gets a JSON POST when the job starts, for each
                    finished page, and when the job ends. headers are sent with
                    every call, metadata comes back in every call, and events
                    picks which of started, page, action, completed, failed and
                    cancelled to send (all by default). An agent run sends
                    action for each step it takes, and page too. Every call is
                    signed: read Stophy-Signature (t=<unix seconds>,v1=<hex>),
                    where v1 is the HMAC-SHA256 of "<t>.<body>" with your
                    webhook secret from webhook.secret. A call that gets no 2xx
                    is sent again, up to 3 times. If your address answers
                    slowly, a page event can carry only the page url. Read that
                    page with the status call.
                  anyOf:
                    - type: string
                    - type: object
                      properties:
                        url:
                          type: string
                        headers:
                          type: object
                          propertyNames:
                            type: string
                            pattern: ^[A-Za-z0-9-]{1,64}$
                          additionalProperties:
                            type: string
                            maxLength: 1000
                        metadata:
                          type: object
                          propertyNames:
                            type: string
                          additionalProperties:
                            $ref: '#/components/schemas/agent.input.schema0'
                        events:
                          minItems: 1
                          type: array
                          items:
                            type: string
                            enum:
                              - started
                              - page
                              - action
                              - completed
                              - failed
                              - cancelled
                      required:
                        - url
                      additionalProperties: false
              required:
                - prompt
              additionalProperties: false
            example:
              prompt: What is the name of the configuration file this page describes?
              urls:
                - https://bun.com/docs/runtime/bunfig
              schema:
                type: object
                properties:
                  file:
                    type: string
              maxCredits: 10
      responses:
        '200':
          description: The data, and what this call cost in dollars.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/RequestId'
            x-credits-used:
              $ref: '#/components/headers/CreditsUsed'
            x-cost-usd:
              $ref: '#/components/headers/CostUsd'
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/RateLimitReset'
            x-cache:
              $ref: '#/components/headers/Cache'
            x-cache-age:
              $ref: '#/components/headers/CacheAge'
          content:
            application/json:
              schema:
                type: object
                additionalProperties: false
                properties:
                  success:
                    type: boolean
                    const: true
                  id:
                    type: string
                  url:
                    type: string
                  status:
                    type: string
                    const: scraping
                  queuePosition:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  threadId:
                    type: string
                  threadTurn:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  creditsUsed:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  costUsd:
                    type: number
                  requestId:
                    type: string
                required:
                  - success
                  - threadTurn
                  - creditsUsed
                  - costUsd
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/Error'
components:
  parameters:
    MaxTextLength:
      name: maxTextLength
      in: query
      required: false
      description: >-
        Cut every text value in the response to this many characters. A value
        that was cut ends with …, and a page whose text was cut has isTruncated
        set to true. A screenshot is never cut. Leave it out to get the full
        text.
      schema:
        type: integer
        minimum: 1
  schemas:
    agent.input.schema0:
      anyOf:
        - type: string
        - type: number
        - type: boolean
        - type: 'null'
        - type: array
          items:
            $ref: '#/components/schemas/agent.input.schema0'
        - type: object
          propertyNames:
            type: string
          additionalProperties:
            $ref: '#/components/schemas/agent.input.schema0'
    Error:
      type: object
      required:
        - success
        - error
        - code
      properties:
        success:
          const: false
        error:
          type: string
          description: What went wrong and what to do next.
        code:
          type: string
          enum:
            - apiKeyRequired
            - busy
            - checkRunning
            - cliSessionCompleted
            - cliSessionExists
            - cliSessionNotFound
            - forbidden
            - freeLimit
            - insufficientCredits
            - internalError
            - inviteClaimed
            - inviteDisabled
            - inviteExpired
            - inviteUsedUp
            - invalidCliSession
            - invalidCliVerifier
            - invalidRequest
            - jobFinished
            - methodNotAllowed
            - notFound
            - payloadTooLarge
            - profileBusy
            - profileTooLarge
            - prohibitedPermission
            - promptInjectionDetected
            - rateLimited
            - sourceChanged
            - sourceRefused
            - siteNotRead
            - sourceTimeout
            - sourceUnavailable
            - unauthorized
            - unsupportedMediaType
        retryable:
          type: boolean
          description: true when trying again can help.
        retryAfterSeconds:
          type: integer
        requestId:
          type: string
        requiredCredits:
          type: number
          description: >-
            Older field: the most the call can cost, in $0.002 steps. Sent when
            the balance is too low.
        availableCredits:
          type: number
          description: 'Older field: the balance in $0.002 steps. Sent with requiredCredits.'
        requiredUsd:
          type: number
          description: >-
            The most the call can cost, in dollars. Sent when the balance is too
            low.
        availableUsd:
          type: number
          description: What is left on the account, in dollars. Sent with requiredUsd.
        billingUrl:
          type: string
          description: Where to add money. Sent with requiredUsd.
        signupUrl:
          type: string
          const: https://stophy.dev/signup
          description: >-
            Where a person gets a key. Sent with apiKeyRequired, freeLimit and
            an invalid key.
        signup:
          type: string
          const: POST https://api.stophy.dev/v1/signup
          description: >-
            The call that gets an agent a key with no human. Sent next to
            signupUrl.
  headers:
    RequestId:
      description: The request id. Quote it when you report a problem.
      schema:
        type: string
    CreditsUsed:
      description: >-
        Older header: what this call cost, as whole steps of $0.002. Use
        x-cost-usd.
      schema:
        type: integer
    CostUsd:
      description: What this call cost, in dollars.
      schema:
        type: string
    RateLimitLimit:
      description: Requests allowed in the current window.
      schema:
        type: integer
    RateLimitRemaining:
      description: Requests left in the current window.
      schema:
        type: integer
    RateLimitReset:
      description: Unix time in seconds when the current window resets.
      schema:
        type: integer
    Cache:
      description: hit if this result came from the cache, miss if it was fetched live.
      schema:
        type: string
    CacheAge:
      description: Seconds since the returned result was written to the cache.
      schema:
        type: integer
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
  responses:
    Error:
      description: The request failed. Retry-After says when trying again can help.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.