Parcha Agent API

openapi: 3.0.0
info:
  title: Parcha Admin Agent API
  version: 1.0.0
  description: API for managing Parcha jobs and checks
servers:
- url: https://api.parcha.ai/api/v1
  description: Agent Hub API server
- url: https://demo.parcha.ai/api/v1
  description: Sandbox API server
- url: https://us1.parcha.ai/api/v1
  description: Legacy API server
- url: http://{your-company-domain}.parcha.ai/api/v1
  description: Custom Enterpris server (your company's API server)
security:
- bearerAuth: []
tags:
- name: Agent
paths:
  /agent/config:
    get:
      security:
      - bearerAuth: []
      summary: Get agent configuration
      description: Get the complete agent information including config by its key with visibility metadata
      parameters:
      - name: agent_key
        in: query
        required: true
        schema:
          type: string
        description: The agent key
      responses:
        '200':
          description: Agent configuration retrieved successfully
        '404':
          description: Agent not found
        '500':
          description: Failed to get agent
      tags:
      - Agent
  /api/v1/agent/config:
    get:
      summary: Get Agent Config Route
      description: Get the complete agent information including config by its key with visibility metadata
      operationId: get_agent_config_route_api_v1_agent_config_get
      security:
      - HTTPBearer: []
      parameters:
      - name: agent_key
        in: query
        required: true
        schema:
          type: string
          title: Agent Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Agent
components:
  schemas:
    StepConfig-Output:
      properties:
        step_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Step Name
        step_number:
          anyOf:
          - type: integer
          - type: 'null'
          title: Step Number
        command_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Command Type
          default: tool
        command_id:
          type: string
          title: Command Id
        command_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Command Name
        command_desc:
          anyOf:
          - type: string
          - type: 'null'
          title: Command Desc
        input_schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Input Schema
        data_loader_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Data Loader Id
        data_loader:
          anyOf:
          - type: string
          - type: 'null'
          title: Data Loader
        instructions:
          anyOf:
          - type: string
          - type: 'null'
          title: Instructions
        tool_args:
          anyOf:
          - type: object
          - type: 'null'
          title: Tool Args
        command_instance_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Command Instance Id
        data_loader_args:
          anyOf:
          - type: object
          - type: 'null'
          title: Data Loader Args
        agent_config:
          anyOf:
          - $ref: '#/components/schemas/AgentConfig-Output'
          - type: 'null'
        arg_schemas:
          anyOf:
          - additionalProperties:
              type: object
            type: object
          - type: 'null'
          title: Arg Schemas
        data_loader_arg_schemas:
          anyOf:
          - additionalProperties:
              type: object
            type: object
          - type: 'null'
          title: Data Loader Arg Schemas
        on_check_failure:
          anyOf:
          - type: string
          - type: 'null'
          title: On Check Failure
        run_check_config:
          anyOf:
          - $ref: '#/components/schemas/RunCheckConfig'
          - type: 'null'
          description: Run check config
          default:
            recommendation_options:
              Approve: Select this option if the check passes (passed = true) and there are no fraud-related alerts.
              Review: Select this option if the check failed (passed = false) because the document didn't meet one of the passing criteria.
            answer_prompt: A very brief explanation (1-2 sentences) of the given recommendation.
            follow_up_prompt: "\n            Procedure: \n            If the recommendation is 'Review', provide the customer with instructions about what do they need to \n            do differently. Use the step_config info for reference.  If the document didn't meet with \n            the passing guidelines, provide the customer with a list of the items they need to correct. \n            E.g. if the document failed because its validity period is invalid, provide the customer with the \n            validity period and any context it may help them to clear this task. Sign the message as 'FastBank'.\n        \n            Constrains:\n            Remember, you are a very helpful customer assistant. Act like one.\n            This field should be formatted in Markdown using the CommonMark specs. This field will be directly shown to a customer, \n            so formatting, as well as cordial language, will be extremely important.\n        "
        skip_finish_plan:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Skip Finish Plan
          default: false
        flash_check_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Flash Check Id
        flash_check_args:
          anyOf:
          - type: object
          - type: 'null'
          title: Flash Check Args
        enabled:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Enabled
          default: true
        credits_cost:
          anyOf:
          - type: number
            minimum: 0.0
          - type: 'null'
          title: Credits Cost
          description: Credits cost for this step/check
      type: object
      required:
      - command_id
      title: StepConfig
    AgentConfig-Output:
      properties:
        agent_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Key
        agent_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Name
        agent_description:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Description
        agent_sop:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Sop
        agent_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Type
        objective:
          anyOf:
          - type: string
          - type: 'null'
          title: Objective
        input_transform_prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: Input Transform Prompt
        input_prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: Input Prompt
        output_sop:
          anyOf:
          - type: string
          - additionalProperties:
              items:
                type: string
              type: array
            type: object
          - type: 'null'
          title: Output Sop
        category_config:
          anyOf:
          - $ref: '#/components/schemas/CategoryConfig'
          - type: 'null'
        llm_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Llm Name
        output_type:
          anyOf:
          - $ref: '#/components/schemas/OutputType'
          - type: 'null'
        steps:
          items:
            $ref: '#/components/schemas/StepConfig-Output'
          type: array
          title: Steps
        input_schema:
          anyOf:
          - items:
              type: object
            type: array
          - type: 'null'
          title: Input Schema
        data_loader_ids:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Data Loader Ids
        benchmarks:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Benchmarks
          default: false
        form_fields:
          anyOf:
          - items:
              type: string
            type: array
          - items:
              $ref: '#/components/schemas/FormField'
            type: array
          - type: 'null'
          title: Form Fields
        save_report_to_gdrive:
          anyOf:
          - type: string
          - type: 'null'
          title: Save Report To Gdrive
        save_report_to_gcs:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Save Report To Gcs
          default: false
        split_first_name:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Split First Name
          default: false
        allow_data_extraction:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Allow Data Extraction
          default: false
        fail_on_error:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Fail On Error
          default: false
        enable_job_batching:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Enable Job Batching
          default: false
        icon:
          anyOf:
          - type: string
          - type: 'null'
          title: Icon
        select_profile_ids:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Select Profile Ids
          default: false
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
      type: object
      required:
      - steps
      title: AgentConfig
    CategoryConfig:
      properties:
        categories:
          items:
            $ref: '#/components/schemas/CategoryDefinition'
          type: array
          title: Categories
          description: List of category definitions
        default_category:
          anyOf:
          - type: string
          - type: 'null'
          title: Default Category
          description: Default category value when no criteria match
      type: object
      required:
      - categories
      title: CategoryConfig
      description: Configuration for flexible categories in finish plan tools
    CategoryDefinition:
      properties:
        name:
          type: string
          title: Name
          description: Display name for the category (e.g., 'High Risk', 'Qualified', 'MCC 1234')
        value:
          type: string
          title: Value
          description: Internal value for the category (used in code and API responses)
        criteria:
          items:
            type: string
          type: array
          title: Criteria
          description: List of criteria that define when this category applies
        color:
          type: string
          title: Color
          description: 'Color code for UI display (hex code like #FF0000)'
        priority:
          type: integer
          title: Priority
          description: Priority for category matching (higher number = higher priority)
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Optional description of the category
      type: object
      required:
      - name
      - value
      - criteria
      - color
      - priority
      title: CategoryDefinition
      description: Definition of a single category for flexible finish plan tools
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    FormField:
      properties:
        type:
          type: string
          title: Type
        fields:
          items:
            type: string
          type: array
          title: Fields
      type: object
      required:
      - type
      - fields
      title: FormField
      description: Model representing a form field type with its associated fields.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AgentResponse:
      properties:
        agent_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Key
        agent_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Name
        agent_description:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Description
        agent_sop:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Sop
        agent_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Type
        objective:
          anyOf:
          - type: string
          - type: 'null'
          title: Objective
        input_transform_prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: Input Transform Prompt
        input_prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: Input Prompt
        output_sop:
          anyOf:
          - type: string
          - additionalProperties:
              items:
                type: string
              type: array
            type: object
          - type: 'null'
          title: Output Sop
        category_config:
          anyOf:
          - $ref: '#/components/schemas/CategoryConfig'
          - type: 'null'
        llm_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Llm Name
        output_type:
          anyOf:
          - $ref: '#/components/schemas/OutputType'
          - type: 'null'
        steps:
          items:
            $ref: '#/components/schemas/StepConfig-Output'
          type: array
          title: Steps
        input_schema:
          anyOf:
          - items:
              type: object
            type: array
          - type: 'null'
          title: Input Schema
        data_loader_ids:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Data Loader Ids
        benchmarks:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Benchmarks
          default: false
        form_fields:
          anyOf:
          - items:
              type: string
            type: array
          - items:
              $ref: '#/components/schemas/FormField'
            type: array
          - type: 'null'
          title: Form Fields
        save_report_to_gdrive:
          anyOf:
          - type: string
          - type: 'null'
          title: Save Report To Gdrive
        save_report_to_gcs:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Save Report To Gcs
          default: false
        split_first_name:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Split First Name
          default: false
        allow_data_extraction:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Allow Data Extraction
          default: false
        fail_on_error:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Fail On Error
          default: false
        enable_job_batching:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Enable Job Batching
          default: false
        icon:
          anyOf:
          - type: string
          - type: 'null'
          title: Icon
        select_profile_ids:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Select Profile Ids
          default: false
        created_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Created At
        agent_db_id:
          type: string
          format: uuid
          title: Agent Db Id
        tenant_id:
          type: string
          title: Tenant Id
        status:
          $ref: '#/components/schemas/AgentStatus'
        rbac:
          type: boolean
          title: Rbac
        is_base_model:
          type: boolean
          title: Is Base Model
        is_visible:
          type: boolean
          title: Is Visible
          default: true
        agent_db_created_at:
          type: string
          format: date-time
          title: Agent Db Created At
        agent_db_updated_at:
          type: string
          format: date-time
          title: Agent Db Updated At
        base_agent_version:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Base Agent Version
        version_id:
          type: string
          format: uuid
          title: Version Id
        version_number:
          type: integer
          title: Version Number
        version_modified_by:
          anyOf:
          - type: string
          - type: 'null'
          title: Version Modified By
        version_created_at:
          type: string
          format: date-time
          title: Version Created At
        version_updated_at:
          type: string
          format: date-time
          title: Version Updated At
        version_comments:
          anyOf:
          - type: string
          - type: 'null'
          title: Version Comments
        job_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Job Count
          default: 0
        worker_compatible:
          type: boolean
          title: Worker Compatible
          default: false
        supported_input_schemas:
          items:
            type: string
          type: array
          title: Supported Input Schemas
      type: object
      required:
      - steps
      - agent_db_id
      - tenant_id
      - status
      - rbac
      - is_base_model
      - agent_db_created_at
      - agent_db_updated_at
      - version_id
      - version_number
      - version_created_at
      - version_updated_at
      title: AgentResponse
      description: 'Flattened response model for an agent, combining Agent, AgentVersion, and AgentConfig (from models_003) data.

        Inherits all behavioral fields (including ''steps'') from ai.agent_003.models_003.AgentConfig.'
    AgentStatus:
      type: string
      enum:
      - draft
      - active
      - deprecated
      title: AgentStatus
      description: Tracks the lifecycle status of an agent version
    OutputType:
      type: string
      enum:
      - assessment
      - mcc_code
      - risk_rating
      - match_rating
      - custom_categories
      title: OutputType
    RunCheckConfig:
      properties:
        recommendation_options:
          anyOf:
          - additionalProperties:
              type: string
            type: object
          - type: 'null'
          title: Recommendation Options
        answer_prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: Answer Prompt
        follow_up_prompt:
          anyOf:
          - type: string
          - type: 'null'
          title: Follow Up Prompt
      type: object
      title: RunCheckConfig
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key obtained from your Parcha account settings. Include as Bearer token in the Authorization header.