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

# Run Document Agent

> Run a published agent processor on a document. Address it with processor=<id>, optionally pinned to a version as <id>@<version>; omit the version to run the newest published one. The run configuration comes entirely from the processor's frozen contract.

This is the successor to the deprecated /custom-processor endpoint: a custom processor cp_xxx is addressable here as processor=cp_xxx.



## OpenAPI

````yaml https://www.datalab.to/openapi.json post /api/v1/agent
openapi: 3.1.0
info:
  title: Datalab API
  version: 0.0.1
servers:
  - url: https://www.datalab.to
    description: Datalab API
security: []
paths:
  /api/v1/agent:
    post:
      summary: Run Document Agent
      description: >-
        Run a published agent processor on a document. Address it with
        processor=<id>, optionally pinned to a version as <id>@<version>; omit
        the version to run the newest published one. The run configuration comes
        entirely from the processor's frozen contract.


        This is the successor to the deprecated /custom-processor endpoint: a
        custom processor cp_xxx is addressable here as processor=cp_xxx.
      operationId: agent_api_v1_agent_post
      parameters:
        - name: wos-session
          in: cookie
          required: false
          schema:
            type: string
            title: Wos-Session
        - name: datalab_active_team
          in: cookie
          required: false
          schema:
            type: string
            title: Datalab Active Team
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_agent_api_v1_agent_post'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InitialResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    Body_agent_api_v1_agent_post:
      properties:
        file_url:
          anyOf:
            - type: string
            - type: 'null'
          title: File Url
          description: >-
            Optional file URL (http/https). If provided, the server will
            download and process it.
        processor:
          type: string
          title: Processor
          description: >-
            A published agent processor address, e.g. 'cp_abc123' or
            'cp_abc123@2.0'. Omit the version to run the newest published one.
        verification_effort:
          type: string
          title: Verification Effort
          description: >-
            How much verification the agent run does before it may finish. One
            of 'fast', 'balanced', 'accurate'.
          default: fast
        return_images:
          type: boolean
          title: Return Images
          description: Return the run's images inline as base64 (parse render shapes only).
          default: false
        skip_cache:
          type: boolean
          title: Skip Cache
          description: Skip the cache and re-run the request.
          default: false
        webhook_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Webhook Url
          description: Optional webhook URL to call when the request is complete.
        processing_location:
          anyOf:
            - type: string
            - type: 'null'
          title: Processing Location
          description: >-
            Optional residency region override (e.g. us, eu). When provided, use
            file_url or direct-upload; multipart uploads are rejected. When
            omitted, the request uses the team's configured residency and
            profile.
        file:
          anyOf:
            - type: string
              contentMediaType: application/octet-stream
            - type: 'null'
          title: File
          description: >-
            Input PDF, image, office document (doc/docx/ppt/pptx), HTML, EPUB,
            or spreadsheet (xlsx/xlsm/xls/ods/csv) file, uploaded as multipart
            form data. Office documents are converted to PDF before the agent
            runs; spreadsheets are processed per-sheet.
      type: object
      required:
        - processor
      title: Body_agent_api_v1_agent_post
    InitialResponse:
      properties:
        success:
          type: boolean
          title: Success
          description: Whether the request was successful.
          default: true
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
          description: >-
            If the request was not successful, this will contain an error
            message.
        request_id:
          type: string
          title: Request Id
          description: >-
            The ID of the request. This ID can be used to check the status of
            the request.
        request_check_url:
          type: string
          title: Request Check Url
          description: The URL to check the status of the request and get results.
        versions:
          anyOf:
            - additionalProperties: true
              type: object
            - type: string
            - type: 'null'
          title: Versions
          description: A dictionary of the versions of the libraries used in the request.
        checkpoint_reused:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Checkpoint Reused
          description: >-
            True when this run automatically reused a checkpoint from a previous
            run of the same file, so the conversion step is not re-billed.
            Absent/None otherwise.
      type: object
      required:
        - request_id
        - request_check_url
      title: InitialResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key

````