1Fort Email AI Agent API

openapi: 3.2.0
info:
  title: 1Fort API Documentation Email AI Agent API
  description: '# 1Fort API


    REST API for the 1Fort insurance platform. This document is the authoritative

    map of the API surface; endpoints are grouped in the sidebar by **app** and

    **version**, and large apps are split into per-resource sub-groups.


    ## Authentication


    Almost every endpoint requires a **JWT access token**. Send it in the

    `Authorization` header as either `Bearer <token>` or `JWT <token>`. Tokens may

    also be presented as an HTTP-only cookie. Endpoints documented with no security

    requirement are intentionally public (for example sign-in, OTP and storefront

    endpoints).


    ## Multi-tenancy


    Resources are scoped to a tenant. Nested routes carry the owning resource id in

    the path (for example `/v2/broker/{business_pk}/applications`); a token is only

    authorised for the businesses its user may access. Object-level permissions are

    enforced per endpoint.


    ## Versioning


    `v2` endpoints live under `/apis/v2/...` and are the current surface. `v1`

    endpoints remain documented for compatibility. Endpoints marked **deprecated**

    are scheduled for removal; prefer the documented replacement.

    '
  termsOfService: https://www.1fort.com/
  license:
    name: Privately owned
  version: v1
servers:
- url: https://api.1fort.com/apis/
security:
- Bearer: []
tags:
- name: Email AI Agent
  x-displayName: Email AI Agent
  description: '**Access:** requires a JWT access token.'
paths:
  /v2/broker/agent/emails/{email_pk}/attachments/{id}:
    parameters:
    - name: email_pk
      in: path
      required: true
      schema:
        type: string
    - name: id
      in: path
      description: A UUID string identifying this Email Attachment.
      required: true
      schema:
        type: string
        format: uuid
    get:
      operationId: agent_get_attachment
      summary: Get Attachment Metadata
      description: '

        Retrieve attachment metadata from the database.


        Use this endpoint to get attachment details before downloading content:

        - File information (name, mime_type, size)

        - Processing status

        - Document type (if classified)

        - Metadata


        **Authentication**: Requires API Key + Session Token


        **Scoping**: Attachment must belong to an email within the session''s broker scope.

        '
      parameters:
      - name: X-Processing-Session
        in: header
        description: Processing session token (scopes access to broker)
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Attachment metadata retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentAttachmentDetail'
        '401':
          description: Unauthorized - Invalid or missing API key or session token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: UNAUTHORIZED
                  message: Invalid or missing authentication credentials
        '403':
          description: Forbidden - Resource belongs to unauthorized broker
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: FORBIDDEN
                  message: Access denied - resource outside session scope
        '404':
          description: Not Found - Resource does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: NOT_FOUND
                  message: Resource not found
        '500':
          description: Internal server error.
      tags:
      - Email AI Agent
  /v2/broker/agent/emails/{email_pk}/attachments/{id}/content:
    parameters:
    - name: email_pk
      in: path
      required: true
      schema:
        type: string
    - name: id
      in: path
      description: A UUID string identifying this Email Attachment.
      required: true
      schema:
        type: string
        format: uuid
    get:
      operationId: agent_get_attachment_content
      summary: Get Attachment Content
      description: "\nDownload the binary content of an attachment file.\n\nReturns the actual file content for document processing:\n- Content-Type header set to the file's MIME type\n- Content-Disposition header with filename\n- Binary file content in response body\n\n**Usage**:\n```python\nresponse = requests.get(\n    f\"{BASE_URL}/emails/{email_id}/attachments/{attachment_id}/content\",\n    headers={\"Authorization\": f\"Api-Key {API_KEY}\", \"X-Processing-Session\": token},\n    stream=True\n)\nwith open(\"/tmp/document.pdf\", \"wb\") as f:\n    for chunk in response.iter_content(chunk_size=8192):\n        f.write(chunk)\n```\n\n**Authentication**: Requires API Key + Session Token\n\n**Scoping**: Attachment must belong to an email within the session's broker scope.\n"
      parameters:
      - name: X-Processing-Session
        in: header
        description: Processing session token (scopes access to broker)
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Attachment file content
          content:
            application/json:
              schema:
                type: string
                format: binary
        '401':
          description: Unauthorized - Invalid or missing API key or session token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: UNAUTHORIZED
                  message: Invalid or missing authentication credentials
        '403':
          description: Forbidden - Resource belongs to unauthorized broker
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: FORBIDDEN
                  message: Access denied - resource outside session scope
        '404':
          description: Not Found - Attachment or file does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: FILE_NOT_FOUND
                  message: Attachment file is missing from storage
        '500':
          description: Internal server error.
      tags:
      - Email AI Agent
  /v2/broker/agent/emails/{id}:
    parameters:
    - name: id
      in: path
      description: A UUID string identifying this Email.
      required: true
      schema:
        type: string
        format: uuid
    get:
      operationId: agent_get_email
      summary: Get Email
      description: '

        Retrieve a single email with full context for processing.


        Returns the complete email data including:

        - Email content (subject, body)

        - Participants (sender, to, cc, bcc)

        - Metadata (received_at, direction, provider, thread_id)

        - Current classification and processing status

        - User information (email owner with broker_id for scoping)

        - All attachments with metadata


        **Authentication**: Requires API Key + Session Token


        **Scoping**: Email must belong to a broker within the session''s scope.

        '
      parameters:
      - name: X-Processing-Session
        in: header
        description: Processing session token (scopes access to broker)
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Email retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentEmailDetail'
        '401':
          description: Unauthorized - Invalid or missing API key or session token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: UNAUTHORIZED
                  message: Invalid or missing authentication credentials
        '403':
          description: Forbidden - Resource belongs to unauthorized broker
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: FORBIDDEN
                  message: Access denied - resource outside session scope
        '404':
          description: Not Found - Resource does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: NOT_FOUND
                  message: Resource not found
        '500':
          description: Internal server error.
      tags:
      - Email AI Agent
    patch:
      operationId: agent_update_email
      summary: Update Email
      description: "\nUpdate email classification and/or processing status.\n\nUse this endpoint to:\n- Set the classification (COMMERCIAL_INSURANCE, PERSONAL_INSURANCE, etc.)\n- Update the processing status. Valid values: `SYNCING`, `READY`,\n  `PROCESSING`, `COMPLETED`, `FAILED`, `SKIPPED`, `LINKED`. `COMPLETED`\n  and `SKIPPED` are terminal — further updates return 409.\n- Optionally include classification details (method, confidence, reasoning)\n\nAt least one of `classification` or `processing_status` must be provided.\n\n**Authentication**: Requires API Key + Session Token\n\n**Scoping**: Email must belong to a broker within the session's scope.\n"
      parameters:
      - name: X-Processing-Session
        in: header
        description: Processing session token (scopes access to broker)
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Email updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentEmailUpdateResponse'
        '400':
          description: Bad Request - Invalid classification or status value
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - Invalid or missing API key or session token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: UNAUTHORIZED
                  message: Invalid or missing authentication credentials
        '403':
          description: Forbidden - Resource belongs to unauthorized broker
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: FORBIDDEN
                  message: Access denied - resource outside session scope
        '404':
          description: Not Found - Resource does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: NOT_FOUND
                  message: Resource not found
        '409':
          description: Conflict - Email already in terminal state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error.
      tags:
      - Email AI Agent
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentEmailUpdate'
        required: true
  /v2/broker/agent/emails/{id}/content:
    parameters:
    - name: id
      in: path
      description: A UUID string identifying this Email.
      required: true
      schema:
        type: string
        format: uuid
    get:
      operationId: agent_get_email_content
      summary: Get Email Content
      description: '

        Retrieve the full email body content.


        Use this endpoint when you need the complete email body for processing,

        after reviewing the body_snippet from the GET /emails/{id} endpoint.


        **Authentication**: Requires API Key + Session Token


        **Scoping**: Email must belong to a broker within the session''s scope.

        '
      parameters:
      - name: X-Processing-Session
        in: header
        description: Processing session token (scopes access to broker)
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Email content retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentEmailContent'
        '401':
          description: Unauthorized - Invalid or missing API key or session token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: UNAUTHORIZED
                  message: Invalid or missing authentication credentials
        '403':
          description: Forbidden - Resource belongs to unauthorized broker
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: FORBIDDEN
                  message: Access denied - resource outside session scope
        '404':
          description: Not Found - Resource does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: NOT_FOUND
                  message: Resource not found
        '500':
          description: Internal server error.
      tags:
      - Email AI Agent
components:
  schemas:
    AgentEmailUser:
      type: object
      properties:
        id:
          title: Id
          type: string
          format: uuid
          readOnly: true
        email:
          title: Email
          type: string
          format: email
          readOnly: true
          minLength: 1
        display_name:
          title: Display name
          type: string
          readOnly: true
          minLength: 1
        broker_id:
          title: Broker id
          type: string
          readOnly: true
    ErrorResponse:
      required:
      - error
      type: object
      properties:
        error:
          title: Error
          description: Error details with code and message.
          type: object
          additionalProperties:
            type: string
            minLength: 1
        request_id:
          title: Request id
          description: Request ID for debugging.
          type: string
          minLength: 1
        timestamp:
          title: Timestamp
          description: When the error occurred.
          type: string
          format: date-time
    AgentEmailUpdate:
      type: object
      properties:
        classification:
          title: Classification
          description: New classification value for the email.
          type: string
          enum:
          - UNKNOWN
          - INSURANCE_UNKNOWN
          - COMMERCIAL_INSURANCE
          - PERSONAL_INSURANCE
          - NON_INSURANCE
        processing_status:
          title: Processing status
          description: New processing status for the email.
          type: string
          enum:
          - SYNCING
          - READY
          - PROCESSING
          - COMPLETED
          - FAILED
          - SKIPPED
          - LINKED
        classification_details:
          title: Classification details
          description: Metadata about the classification decision (method, confidence, reasoning, etc.).
          type: object
          default: {}
    AgentAttachmentDetail:
      type: object
      properties:
        id:
          title: Id
          type: string
          format: uuid
          readOnly: true
        email_id:
          title: Email id
          type: string
          format: uuid
          readOnly: true
        name:
          title: Name
          type:
          - string
          - 'null'
          readOnly: true
          minLength: 1
        mime_type:
          title: Mime type
          type:
          - string
          - 'null'
          readOnly: true
          minLength: 1
        size:
          title: Size
          type:
          - integer
          - 'null'
          readOnly: true
        document_type:
          title: Document type
          type: string
          readOnly: true
        processing_status:
          title: Processing status
          description: Current processing status for quick filtering
          type: string
          enum:
          - UNPROCESSED
          - QUEUED
          - PROCESSING
          - COMPLETED
          - FAILED
          - SKIPPED
          readOnly: true
        metadata:
          title: Metadata
          type: object
          readOnly: true
        created_at:
          title: Created at
          type: string
          format: date-time
          readOnly: true
    AgentAttachment:
      type: object
      properties:
        id:
          title: Id
          type: string
          format: uuid
          readOnly: true
        name:
          title: Name
          type:
          - string
          - 'null'
          readOnly: true
          minLength: 1
        mime_type:
          title: Mime type
          type:
          - string
          - 'null'
          readOnly: true
          minLength: 1
        size:
          title: Size
          type:
          - integer
          - 'null'
          readOnly: true
        document_type:
          title: Document type
          type:
          - string
          - 'null'
          readOnly: true
          minLength: 1
        processing_status:
          title: Processing status
          description: Current processing status for quick filtering
          type: string
          enum:
          - UNPROCESSED
          - QUEUED
          - PROCESSING
          - COMPLETED
          - FAILED
          - SKIPPED
          readOnly: true
        metadata:
          title: Metadata
          type: object
          readOnly: true
        created_at:
          title: Created at
          type: string
          format: date-time
          readOnly: true
    AgentEmailDetail:
      type: object
      properties:
        id:
          title: Id
          type: string
          format: uuid
          readOnly: true
        subject:
          title: Subject
          type:
          - string
          - 'null'
          readOnly: true
          minLength: 1
        body_snippet:
          title: Body snippet
          type: string
          readOnly: true
        sender:
          title: Sender
          type: object
          readOnly: true
        tos:
          title: Tos
          type: object
          readOnly: true
        ccs:
          title: Ccs
          type: object
          readOnly: true
        bccs:
          title: Bccs
          type: object
          readOnly: true
        received_at:
          title: Received at
          type:
          - string
          - 'null'
          format: date-time
          readOnly: true
        direction:
          title: Direction
          description: Inbound (received by mailbox) or Outbound (sent from mailbox).
          type: string
          enum:
          - INBOUND
          - OUTBOUND
          readOnly: true
        provider:
          title: Provider
          type: string
          enum:
          - OFFICE365
          - GOOGLE
          readOnly: true
        thread_id:
          title: Thread id
          type:
          - string
          - 'null'
          readOnly: true
          minLength: 1
        message_id:
          title: Message id
          type: string
          readOnly: true
          minLength: 1
        classification:
          title: Classification
          description: High-level classification of the email's business relevance.
          type: string
          enum:
          - UNKNOWN
          - INSURANCE_UNKNOWN
          - COMMERCIAL_INSURANCE
          - PERSONAL_INSURANCE
          - NON_INSURANCE
          readOnly: true
        processing_status:
          title: Processing status
          description: Current processing status of the email.
          type: string
          enum:
          - SYNCING
          - READY
          - PROCESSING
          - COMPLETED
          - FAILED
          - SKIPPED
          - LINKED
          readOnly: true
        user:
          $ref: '#/components/schemas/AgentEmailUser'
        broker:
          title: Broker
          type: string
          readOnly: true
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/AgentAttachment'
          readOnly: true
    AgentEmailUpdateResponse:
      type: object
      properties:
        id:
          title: Id
          type: string
          format: uuid
          readOnly: true
        classification:
          title: Classification
          type: string
          readOnly: true
          minLength: 1
        processing_status:
          title: Processing status
          type: string
          readOnly: true
          minLength: 1
        updated_at:
          title: Updated at
          type: string
          format: date-time
          readOnly: true
    AgentEmailContent:
      type: object
      properties:
        id:
          title: Id
          type: string
          format: uuid
          readOnly: true
        body:
          title: Body
          type:
          - string
          - 'null'
          readOnly: true
          minLength: 1
  securitySchemes:
    Bearer:
      type: apiKey
      name: Authorization
      in: header
      description: JWT access token. Send as `Bearer <token>` or `JWT <token>`.
    ApiKey:
      type: apiKey
      name: Authorization
      in: header
      description: API key. Send as `Api-Key <key>`.
x-tagGroups:
- name: Agent runtime (v2)
  tags:
  - agent_runtime (v2)
- name: Analytics
  tags:
  - analytics
- name: Application
  tags:
  - 'application: applications'
  - 'application: clients'
- name: Application (v2)
  tags:
  - 'application (v2): applications'
  - 'application (v2): coverages'
- name: Ascend
  tags:
  - ascend
- name: Ascend (v2)
  tags:
  - ascend (v2)
- name: Authentication
  tags:
  - Authentication
  - auth
- name: Billing (v2)
  tags:
  - billing (v2)
- name: Broker
  tags:
  - broker
  - broker-ams-integration
  - broker-google
  - broker-office365
  - broker-office365-individual
  - 'broker: ai-customization-types'
  - 'broker: ai-customizations'
  - 'broker: clients'
  - 'broker: email_preferences'
  - 'broker: proposal-preferences'
  - 'broker: take-rates'
  - 'broker: user-ai-customizations'
  - 'broker: users'
  - broker_groups
  - broker_settings
- name: Broker (v2)
  tags:
  - 'broker (v2): applications'
  - 'broker (v2): clients'
  - 'broker (v2): coverages'
  - 'broker (v2): email-templates'
  - 'broker (v2): quote-policies'
  - 'broker (v2): quotes'
  - 'broker (v2): storefront'
  - 'broker (v2): team-users'
- name: Business
  tags:
  - business
  - business-broker-users
  - business-user
  - business_admin
- name: Carrier
  tags:
  - carrier
- name: Checkout
  tags:
  - checkout
- name: Email AI
  tags:
  - email_ai
- name: Email AI (v2)
  tags:
  - 'email_ai (v2): attachments'
  - 'email_ai (v2): carriers'
  - 'email_ai (v2): coverage-types'
  - 'email_ai (v2): emails'
  - 'email_ai (v2): gmail'
  - 'email_ai (v2): office365'
  - 'email_ai (v2): profiles'
  - 'email_ai (v2): wholesalers'
- name: Email AI Agent
  tags:
  - Email AI Agent
  - Email AI Agent - Attachments
  - Email AI Agent - Businesses
  - Email AI Agent - Entities
  - Email AI Agent - Markets
  - Email AI Agent - Profiles
  - Email AI Agent - Reference Data
- name: Google workspace (v2)
  tags:
  - google_workspace (v2)
- name: Herald (v2)
  tags:
  - herald (v2)
- name: Indications (v2)
  tags:
  - indications (v2)
- name: Insurance (v2)
  tags:
  - insurance (v2)
- name: Invite
  tags:
  - invite
- name: Legal
  tags:
  - legal
- name: Market
  tags:
  - Markets
  - Markets - Business
- name: Market (v2)
  tags:
  - market (v2)
- name: Office365 (v2)
  tags:
  - office365 (v2)
- name: Premium finance (v2)
  tags:
  - premium_finance (v2)
- name: Quote
  tags:
  - 'quote: applications'
  - 'quote: clients'
  - 'quote: quotes'
- name: Quote (v2)
  tags:
  - 'quote (v2): application'
  - 'quote (v2): binders'
  - 'quote (v2): checkout'
  - 'quote (v2): cios'
  - 'quote (v2): coverages'
  - 'quote (v2): quote-policies'
  - 'quote (v2): quotes'
  - 'quote (v2): tasks'
  - quote_ai (v2)
- name: Reports
  tags:
  - reports
- name: Reward
  tags:
  - reward
- name: Risk manager
  tags:
  - risk_manager
- name: Sanity check AI
  tags:
  - sanity_check_ai
- name: Storefront (v2)
  tags:
  - storefront (v2)
- name: Stripe
  tags:
  - stripe
- name: Suggestion AI
  tags:
  - suggestion_ai
- name: Treasury (v2)
  tags:
  - treasury (v2)
- name: User
  tags:
  - user
  - 'user: default-access-role'