> ## 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.

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.

```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}'
```

```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
}
```


## 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.


    The x-cost-usd response header is what the request cost in dollars. An
    operation's description gives its pricing units and add-ons. The OpenAPI
    fields x-cost-usd and x-cost-usd-max are list-price estimates, not receipts
    or spending limits. When a call starts a job, check the job result for its
    total cost.


    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 $0.003 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'
        - $ref: '#/components/parameters/IdempotencyKey'
      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 $0.003 per reply, 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. Every call has an eventId that
                    stays the same when the call is sent again, so you can skip
                    one you already handled. 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'
            idempotent-replayed:
              $ref: '#/components/headers/IdempotentReplayed'
          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
                required:
                  - success
                  - threadTurn
        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
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        A value you choose for one call. Send the same key with the same method,
        path and body within 24 hours and the first answer comes back with
        idempotent-replayed: true, with the same cost headers and no second
        charge. A call that sends zeroDataRetention and answers with page data
        is not kept, so a retry runs again. Needs an API key.
      schema:
        type: string
  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
    IdempotentReplayed:
      description: >-
        true when this call reuses the result of an earlier call with the same
        Idempotency-Key.
      schema:
        type: string
    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.