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

# Parse

> Turn a PDF, Word, Excel, PowerPoint or HTML file, or a picture of text, into markdown.

Best for a file you already hold.

> [!NOTE]
>
> Works without an API key within the free limits. See [Rate limits](https://docs.stophy.dev/production/rate-limits.md).

```bash cURL theme={null}
curl -X POST https://api.stophy.dev/v1/parse \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"file":"PGgxPkhvdyB0aWRlcyB3b3JrPC9oMT4=","filename":"tides.html"}'
```

```json 200 theme={null}
{
  "success": true,
  "data": {
    "markdown": "# How tides work",
    "metadata": {
      "contentType": "text/html",
      "costUsd": 0.0005
    }
  }
}
```


## OpenAPI

````yaml api-reference/openapi.json POST /v1/parse
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/parse:
    post:
      summary: >-
        Turn a PDF, Word, Excel, PowerPoint or HTML file, or a picture of text,
        into markdown
      description: >-
        Costs $0.50 per 1,000 pages or files whose text comes from a text layer,
        and $2.50 per 1,000 pages or pictures read from their picture, up to
        maxPages; summary and json with a schema or a prompt add $3 per 1,000
        each; zero data retention adds $2 per 1,000 calls. metadata.costUsd
        shows what the call cost in dollars.
      operationId: parse
      parameters:
        - $ref: '#/components/parameters/MaxTextLength'
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                formats:
                  description: >-
                    What to send back besides markdown: summary, html and
                    rawHtml (HTML files only), links, images, or { type: json,
                    schema or prompt }. markdown is always sent.
                  minItems: 1
                  maxItems: 8
                  type: array
                  items:
                    anyOf:
                      - type: object
                        properties:
                          type:
                            type: string
                            const: json
                          prompt:
                            type: string
                            minLength: 1
                            maxLength: 2000
                          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/parse.input.schema0'
                        required:
                          - type
                        additionalProperties: false
                      - anyOf:
                          - type: string
                            enum:
                              - markdown
                              - summary
                              - html
                              - rawHtml
                              - links
                              - images
                          - type: object
                            properties:
                              type:
                                type: string
                                enum:
                                  - markdown
                                  - summary
                                  - html
                                  - rawHtml
                                  - links
                                  - images
                            required:
                              - type
                            additionalProperties: false
                parsers:
                  description: How to read PDF pages. Other files ignore it.
                  maxItems: 1
                  type: array
                  items:
                    type: object
                    properties:
                      type:
                        type: string
                        const: pdf
                      mode:
                        description: >-
                          fast reads the text layer only. auto (the default)
                          reads the text layer and reads the picture of any page
                          that has none. ocr reads the picture of every page.
                        type: string
                        enum:
                          - fast
                          - auto
                          - ocr
                      maxPages:
                        description: Read at most this many pages, up to 100.
                        type: integer
                        minimum: 1
                        maximum: 100
                      pages:
                        description: >-
                          Send true to also get each page's markdown in pages,
                          as { pageNumber, markdown }. No extra charge.
                        type: boolean
                      blocks:
                        description: >-
                          Send true to also get the page's layout in blocks:
                          each title, section header or run of text, with its
                          page, reading order, position on the page (bbox as
                          left, top, right, bottom from 0 to 1) and where its
                          text sits in that page's markdown (span, as in pages).
                          Tables, figures and formulas are not told apart. A
                          page read from its picture is one block. No extra
                          charge.
                        type: boolean
                      pageMarkers:
                        description: >-
                          Send true to mark page breaks in the markdown: pages
                          are joined with "---" and a <!-- page N --> line,
                          where N is the page that follows. No extra charge.
                        type: boolean
                    required:
                      - type
                    additionalProperties: false
                onlyMainContent:
                  description: >-
                    For an HTML file: send false to keep navigation and footers.
                    The default is true.
                  type: boolean
                includeTags:
                  description: 'For an HTML file: keep only what these CSS selectors match.'
                  maxItems: 50
                  type: array
                  items:
                    type: string
                    minLength: 1
                excludeTags:
                  description: 'For an HTML file: drop what these CSS selectors match.'
                  maxItems: 50
                  type: array
                  items:
                    type: string
                    minLength: 1
                removeBase64Images:
                  description: >-
                    For an HTML file: send false to keep images that carry their
                    data in the address.
                  type: boolean
                zeroDataRetention:
                  default: false
                  description: >-
                    Send true to keep nothing from this call: no stored result
                    is read or made, and nothing is logged. Adds $2 per 1,000
                    pages.
                  type: boolean
                origin:
                  description: Which client sent the call. Not used.
                  type: string
                  maxLength: 200
                integration:
                  description: Which integration sent the call. Not used.
                  type: string
                  maxLength: 200
                fastMode:
                  description: >-
                    Page-read speed. Accepted so a client that always sends it
                    works; a file has no page to apply it to, so it is not used.
                mobile:
                  description: >-
                    Mobile page view. Accepted so a client that always sends it
                    works; a file has no page to apply it to, so it is not used.
                blockAds:
                  description: >-
                    Ad blocking. Accepted so a client that always sends it
                    works; a file has no page to apply it to, so it is not used.
                skipTlsVerification:
                  description: >-
                    TLS checks of a page. Accepted so a client that always sends
                    it works; a file has no page to apply it to, so it is not
                    used.
                timeout:
                  description: >-
                    Page load time. Accepted so a client that always sends it
                    works; a file has no page to apply it to, so it is not used.
                headers:
                  description: >-
                    Page request headers. Accepted so a client that always sends
                    it works; a file has no page to apply it to, so it is not
                    used.
                proxy:
                  description: >-
                    Page proxy. Accepted so a client that always sends it works;
                    a file has no page to apply it to, so it is not used.
                location:
                  description: >-
                    Page country and languages. Accepted so a client that always
                    sends it works; a file has no page to apply it to, so it is
                    not used.
                profile:
                  description: >-
                    Saved browser profile. Accepted so a client that always
                    sends it works; a file has no page to apply it to, so it is
                    not used.
                uploadRef:
                  description: >-
                    Instead of file: the uploadId that POST /v1/parse/upload-url
                    returned, after the file was sent to its uploadUrl. The
                    stored file is deleted when the parse ends.
                  type: string
                  pattern: ^upl_[A-Za-z0-9_-]{16,64}$
                file:
                  description: >-
                    The file's bytes as base64, up to 36 MB: a PDF, a Word
                    .docx, an Excel .xlsx, a PowerPoint .pptx, an HTML file or a
                    PNG, JPEG or WebP picture of text.
                  type: string
                  minLength: 1
                filename:
                  description: >-
                    The file's name, such as report.docx. The type is read from
                    the file itself.
                  type: string
                  minLength: 1
                  maxLength: 255
                maxPages:
                  default: 100
                  description: >-
                    Read at most this many PDF pages, sheets or slides;
                    isTruncated says when the file had more. Pages of a PDF with
                    no text layer are read from their picture, up to 20 of them,
                    at $2.50 per 1,000 pages.
                  type: integer
                  minimum: 1
                  maximum: 100
                options:
                  type: object
                  properties:
                    formats:
                      description: >-
                        What to send back besides markdown: summary, html and
                        rawHtml (HTML files only), links, images, or { type:
                        json, schema or prompt }. markdown is always sent.
                      minItems: 1
                      maxItems: 8
                      type: array
                      items:
                        anyOf:
                          - type: object
                            properties:
                              type:
                                type: string
                                const: json
                              prompt:
                                type: string
                                minLength: 1
                                maxLength: 2000
                              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/parse.input.schema0'
                            required:
                              - type
                            additionalProperties: false
                          - anyOf:
                              - type: string
                                enum:
                                  - markdown
                                  - summary
                                  - html
                                  - rawHtml
                                  - links
                                  - images
                              - type: object
                                properties:
                                  type:
                                    type: string
                                    enum:
                                      - markdown
                                      - summary
                                      - html
                                      - rawHtml
                                      - links
                                      - images
                                required:
                                  - type
                                additionalProperties: false
                    parsers:
                      description: How to read PDF pages. Other files ignore it.
                      maxItems: 1
                      type: array
                      items:
                        type: object
                        properties:
                          type:
                            type: string
                            const: pdf
                          mode:
                            description: >-
                              fast reads the text layer only. auto (the default)
                              reads the text layer and reads the picture of any
                              page that has none. ocr reads the picture of every
                              page.
                            type: string
                            enum:
                              - fast
                              - auto
                              - ocr
                          maxPages:
                            description: Read at most this many pages, up to 100.
                            type: integer
                            minimum: 1
                            maximum: 100
                          pages:
                            description: >-
                              Send true to also get each page's markdown in
                              pages, as { pageNumber, markdown }. No extra
                              charge.
                            type: boolean
                          blocks:
                            description: >-
                              Send true to also get the page's layout in blocks:
                              each title, section header or run of text, with
                              its page, reading order, position on the page
                              (bbox as left, top, right, bottom from 0 to 1) and
                              where its text sits in that page's markdown (span,
                              as in pages). Tables, figures and formulas are not
                              told apart. A page read from its picture is one
                              block. No extra charge.
                            type: boolean
                          pageMarkers:
                            description: >-
                              Send true to mark page breaks in the markdown:
                              pages are joined with "---" and a <!-- page N -->
                              line, where N is the page that follows. No extra
                              charge.
                            type: boolean
                        required:
                          - type
                        additionalProperties: false
                    onlyMainContent:
                      description: >-
                        For an HTML file: send false to keep navigation and
                        footers. The default is true.
                      type: boolean
                    includeTags:
                      description: >-
                        For an HTML file: keep only what these CSS selectors
                        match.
                      maxItems: 50
                      type: array
                      items:
                        type: string
                        minLength: 1
                    excludeTags:
                      description: 'For an HTML file: drop what these CSS selectors match.'
                      maxItems: 50
                      type: array
                      items:
                        type: string
                        minLength: 1
                    removeBase64Images:
                      description: >-
                        For an HTML file: send false to keep images that carry
                        their data in the address.
                      type: boolean
                    zeroDataRetention:
                      type: boolean
                    origin:
                      description: Which client sent the call. Not used.
                      type: string
                      maxLength: 200
                    integration:
                      description: Which integration sent the call. Not used.
                      type: string
                      maxLength: 200
                    fastMode:
                      description: >-
                        Page-read speed. Accepted so a client that always sends
                        it works; a file has no page to apply it to, so it is
                        not used.
                    mobile:
                      description: >-
                        Mobile page view. Accepted so a client that always sends
                        it works; a file has no page to apply it to, so it is
                        not used.
                    blockAds:
                      description: >-
                        Ad blocking. Accepted so a client that always sends it
                        works; a file has no page to apply it to, so it is not
                        used.
                    skipTlsVerification:
                      description: >-
                        TLS checks of a page. Accepted so a client that always
                        sends it works; a file has no page to apply it to, so it
                        is not used.
                    timeout:
                      description: >-
                        Page load time. Accepted so a client that always sends
                        it works; a file has no page to apply it to, so it is
                        not used.
                    headers:
                      description: >-
                        Page request headers. Accepted so a client that always
                        sends it works; a file has no page to apply it to, so it
                        is not used.
                    proxy:
                      description: >-
                        Page proxy. Accepted so a client that always sends it
                        works; a file has no page to apply it to, so it is not
                        used.
                    location:
                      description: >-
                        Page country and languages. Accepted so a client that
                        always sends it works; a file has no page to apply it
                        to, so it is not used.
                    profile:
                      description: >-
                        Saved browser profile. Accepted so a client that always
                        sends it works; a file has no page to apply it to, so it
                        is not used.
                  additionalProperties: false
                  description: >-
                    How to read the file and what to send back, with the same
                    names scrape uses for a page.
              additionalProperties: false
            example:
              file: >-
                PGh0bWw+PGhlYWQ+PHRpdGxlPkhvdyB0aWRlcyB3b3JrPC90aXRsZT48L2hlYWQ+PGJvZHk+PG1haW4+PGgxPkhvdyB0aWRlcyB3b3JrPC9oMT48cD5UaGUgTW9vbiBwdWxscyBvbiB0aGUgb2NlYW5zIGFuZCBtYWtlcyB0d28gYnVsZ2VzIG9mIHdhdGVyIHRoYXQgbW92ZSBhcm91bmQgdGhlIEVhcnRoIGFzIGl0IHR1cm5zLCBzbyBtb3N0IGNvYXN0cyBzZWUgdHdvIGhpZ2ggdGlkZXMgYW5kIHR3byBsb3cgdGlkZXMgZXZlcnkgZGF5LjwvcD48L21haW4+PC9ib2R5PjwvaHRtbD4=
              filename: tides.html
      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
                  data:
                    type: object
                    additionalProperties: false
                    properties:
                      markdown:
                        type: string
                      html:
                        type: string
                      rawHtml:
                        type: string
                      links:
                        type: array
                        items:
                          type: string
                      images:
                        type: array
                        items:
                          type: string
                      summary:
                        type: string
                      json:
                        type: object
                        propertyNames:
                          type: string
                        additionalProperties:
                          $ref: '#/components/schemas/parse.schema0'
                      pages:
                        type: array
                        items:
                          type: object
                          propertyNames:
                            type: string
                          additionalProperties:
                            $ref: '#/components/schemas/parse.schema0'
                      blocks:
                        type: array
                        items:
                          type: object
                          propertyNames:
                            type: string
                          additionalProperties:
                            $ref: '#/components/schemas/parse.schema0'
                      warning:
                        type: string
                      metadata:
                        type: object
                        additionalProperties: false
                        properties:
                          title:
                            type: string
                          contentType:
                            type: string
                          numPages:
                            type: integer
                            minimum: -9007199254740991
                            maximum: 9007199254740991
                          ocrPages:
                            type: integer
                            minimum: -9007199254740991
                            maximum: 9007199254740991
                          costUsd:
                            type: number
                        required:
                          - costUsd
                    required:
                      - metadata
                required:
                  - success
                  - data
        4XX:
          $ref: '#/components/responses/Error'
        5XX:
          $ref: '#/components/responses/Error'
      security:
        - apiKey: []
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:
    parse.input.schema0:
      anyOf:
        - type: string
        - type: number
        - type: boolean
        - type: 'null'
        - type: array
          items:
            $ref: '#/components/schemas/parse.input.schema0'
        - type: object
          propertyNames:
            type: string
          additionalProperties:
            $ref: '#/components/schemas/parse.input.schema0'
    parse.schema0:
      anyOf:
        - type: string
        - type: number
        - type: boolean
        - type: 'null'
        - type: array
          items:
            $ref: '#/components/schemas/parse.schema0'
        - type: object
          propertyNames:
            type: string
          additionalProperties:
            $ref: '#/components/schemas/parse.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.