openapi: 3.0.1
info:
  title: Parsio Public API
  description: >-
    Specification of the Parsio public REST API for AI-powered document and email
    parsing. Create and manage mailboxes (parsers), upload documents and emails for
    parsing, retrieve extracted structured JSON, manage parsing templates, and
    configure webhooks for real-time parsed-data delivery. All endpoints require an
    API key supplied via the X-API-Key request header.
  termsOfService: https://parsio.io/terms/
  contact:
    name: Parsio Support
    url: https://help.parsio.io
  version: '1.0'
servers:
  - url: https://api.parsio.io
security:
  - ApiKeyAuth: []
tags:
  - name: Mailboxes
    description: Create and manage mailboxes (parsers) and their table fields.
  - name: Documents
    description: Upload, parse, list, and retrieve documents and their parsed data.
  - name: Templates
    description: Manage parsing templates attached to a mailbox.
  - name: Webhooks
    description: Manage webhooks for real-time parsed-data delivery.
paths:
  /mailboxes:
    get:
      operationId: listMailboxes
      tags:
        - Mailboxes
      summary: List all mailboxes.
      description: Retrieves all mailboxes (parsers) for the authenticated account.
      responses:
        '200':
          description: A list of mailboxes.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Mailbox'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /mailboxes/create:
    post:
      operationId: createMailbox
      tags:
        - Mailboxes
      summary: Create a new mailbox.
      description: Creates a new mailbox (parser) bound to a parsing engine and preset.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMailboxRequest'
      responses:
        '200':
          description: The created mailbox.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Mailbox'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /mailboxes/{mailbox_id}:
    parameters:
      - $ref: '#/components/parameters/MailboxId'
    get:
      operationId: getMailbox
      tags:
        - Mailboxes
      summary: Get a mailbox.
      description: Fetches the settings of a specific mailbox by its ID.
      responses:
        '200':
          description: The requested mailbox.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Mailbox'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: updateMailbox
      tags:
        - Mailboxes
      summary: Update a mailbox.
      description: Updates the configuration of an existing mailbox.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMailboxRequest'
      responses:
        '200':
          description: The updated mailbox.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Mailbox'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteMailbox
      tags:
        - Mailboxes
      summary: Delete a mailbox.
      description: Removes a mailbox and its associated configuration.
      responses:
        '200':
          description: Mailbox deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /mailboxes/{mailbox_id}/tableFields:
    parameters:
      - $ref: '#/components/parameters/MailboxId'
    get:
      operationId: listTableFields
      tags:
        - Mailboxes
      summary: List table fields.
      description: Lists the table fields configured for a mailbox.
      responses:
        '200':
          description: A list of table fields.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TableField'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /mailboxes/{mailbox_id}/doc-sync:
    parameters:
      - $ref: '#/components/parameters/MailboxId'
    post:
      operationId: parseDocumentSync
      tags:
        - Documents
      summary: Parse an HTML or text document synchronously.
      description: >-
        Submits an HTML or plain-text document and waits for the parsing result.
        Supply at least one of html or text; if both are present, html takes
        precedence.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParseDocumentRequest'
      responses:
        '200':
          description: The parsed document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /mailboxes/{mailbox_id}/doc:
    parameters:
      - $ref: '#/components/parameters/MailboxId'
    post:
      operationId: parseDocumentAsync
      tags:
        - Documents
      summary: Parse an HTML or text document asynchronously.
      description: >-
        Submits an HTML or plain-text document for background parsing and returns
        immediately with a document ID. Results are delivered via webhooks or
        retrieved later by document ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ParseDocumentRequest'
      responses:
        '200':
          description: The accepted document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /mailboxes/{mailbox_id}/upload-sync:
    parameters:
      - $ref: '#/components/parameters/MailboxId'
    post:
      operationId: uploadFileSync
      tags:
        - Documents
      summary: Upload a file and wait for the parsing result.
      description: >-
        Uploads a single file (PDF, DOCX, image, HTML, JSON, XML, and more) up to
        20MB and waits for the parsing result.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UploadFileRequest'
      responses:
        '200':
          description: The parsed document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /mailboxes/{mailbox_id}/upload:
    parameters:
      - $ref: '#/components/parameters/MailboxId'
    post:
      operationId: uploadFileAsync
      tags:
        - Documents
      summary: Upload a file for asynchronous parsing.
      description: >-
        Uploads a file (up to 50MB, ZIP archives supported) for background parsing
        and returns immediately. Results are delivered via webhooks or retrieved
        later by document ID.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/UploadFileRequest'
      responses:
        '200':
          description: The accepted document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /mailboxes/{mailbox_id}/docs:
    parameters:
      - $ref: '#/components/parameters/MailboxId'
    get:
      operationId: listDocuments
      tags:
        - Documents
      summary: List documents.
      description: Lists documents in a mailbox with pagination and filters.
      parameters:
        - name: page
          in: query
          schema:
            type: integer
        - name: per_page
          in: query
          schema:
            type: integer
            maximum: 500
        - name: from
          in: query
          description: ISO 8601 start date filter.
          schema:
            type: string
            format: date
        - name: to
          in: query
          description: ISO 8601 end date filter.
          schema:
            type: string
            format: date
        - name: q
          in: query
          description: Free-text search query.
          schema:
            type: string
        - name: status
          in: query
          schema:
            $ref: '#/components/schemas/DocumentStatus'
      responses:
        '200':
          description: A paginated list of documents.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Document'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /mailboxes/{mailbox_id}/docs/skip:
    parameters:
      - $ref: '#/components/parameters/MailboxId'
    post:
      operationId: skipDocuments
      tags:
        - Documents
      summary: Skip documents.
      description: Marks multiple documents as skipped.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdsRequest'
      responses:
        '200':
          description: Documents skipped.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /docs/{document_id}:
    parameters:
      - $ref: '#/components/parameters/DocumentId'
    get:
      operationId: getDocument
      tags:
        - Documents
      summary: Get a parsed document.
      description: Retrieves a document and its extracted structured JSON by ID.
      responses:
        '200':
          description: The requested document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /docs/{document_id}/parse:
    parameters:
      - $ref: '#/components/parameters/DocumentId'
    post:
      operationId: reparseDocument
      tags:
        - Documents
      summary: Reparse a document.
      description: Reprocesses an existing document with the mailbox's current parser.
      responses:
        '200':
          description: The reparsed document.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Document'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /mailboxes/{mailbox_id}/parsed:
    parameters:
      - $ref: '#/components/parameters/MailboxId'
    get:
      operationId: getParsedData
      tags:
        - Documents
      summary: Retrieve parsed data.
      description: Retrieves the parsed data for a mailbox's documents.
      parameters:
        - name: page
          in: query
          schema:
            type: integer
        - name: from
          in: query
          schema:
            type: string
            format: date
        - name: to
          in: query
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Parsed data records.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  additionalProperties: true
        '401':
          $ref: '#/components/responses/Unauthorized'
  /mailboxes/{mailbox_id}/emails:
    parameters:
      - $ref: '#/components/parameters/MailboxId'
    get:
      operationId: listCollectedEmails
      tags:
        - Documents
      summary: Get collected email addresses.
      description: Returns the email addresses collected by a mailbox.
      responses:
        '200':
          description: A list of collected email addresses.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  format: email
        '401':
          $ref: '#/components/responses/Unauthorized'
  /mailboxes/{mailbox_id}/templates:
    parameters:
      - $ref: '#/components/parameters/MailboxId'
    get:
      operationId: listTemplates
      tags:
        - Templates
      summary: List templates.
      description: Lists the parsing templates configured for a mailbox.
      parameters:
        - name: page
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: A list of templates.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Template'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /templates/{template_id}:
    parameters:
      - $ref: '#/components/parameters/TemplateId'
    get:
      operationId: getTemplate
      tags:
        - Templates
      summary: Get a template.
      description: Retrieves the details of a parsing template.
      responses:
        '200':
          description: The requested template.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Template'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /templates/enable_many:
    post:
      operationId: enableTemplates
      tags:
        - Templates
      summary: Enable templates.
      description: Activates multiple parsing templates.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdsRequest'
      responses:
        '200':
          description: Templates enabled.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /templates/disable_many:
    post:
      operationId: disableTemplates
      tags:
        - Templates
      summary: Disable templates.
      description: Deactivates multiple parsing templates.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdsRequest'
      responses:
        '200':
          description: Templates disabled.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /templates/clone_many:
    post:
      operationId: cloneTemplates
      tags:
        - Templates
      summary: Clone templates.
      description: Duplicates multiple parsing templates into a target mailbox.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                ids:
                  type: array
                  items:
                    type: string
                mailbox_id:
                  type: string
      responses:
        '200':
          description: Templates cloned.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /templates:
    delete:
      operationId: deleteTemplates
      tags:
        - Templates
      summary: Delete templates.
      description: Removes multiple parsing templates.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdsRequest'
      responses:
        '200':
          description: Templates deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /webhooks/mb/{mailbox_id}:
    parameters:
      - $ref: '#/components/parameters/MailboxId'
    get:
      operationId: listWebhooks
      tags:
        - Webhooks
      summary: List webhooks for a mailbox.
      description: Lists the webhooks configured for a mailbox.
      responses:
        '200':
          description: A list of webhooks.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Webhook'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /webhooks/{webhook_id}:
    parameters:
      - $ref: '#/components/parameters/WebhookId'
    get:
      operationId: getWebhook
      tags:
        - Webhooks
      summary: Get a webhook.
      description: Retrieves the details of a webhook.
      responses:
        '200':
          description: The requested webhook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /webhooks/{mailbox_id}:
    parameters:
      - $ref: '#/components/parameters/MailboxId'
    post:
      operationId: createWebhook
      tags:
        - Webhooks
      summary: Create a webhook.
      description: Creates a webhook bound to a mailbox for real-time parsed-data delivery.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWebhookRequest'
      responses:
        '200':
          description: The created webhook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /webhooks:
    post:
      operationId: updateWebhook
      tags:
        - Webhooks
      summary: Update a webhook.
      description: Updates an existing webhook identified by its _id.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWebhookRequest'
      responses:
        '200':
          description: The updated webhook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteWebhooks
      tags:
        - Webhooks
      summary: Delete webhooks.
      description: Removes multiple webhooks.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IdsRequest'
      responses:
        '200':
          description: Webhooks deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
  parameters:
    MailboxId:
      name: mailbox_id
      in: path
      required: true
      description: The unique identifier of the mailbox (parser).
      schema:
        type: string
    DocumentId:
      name: document_id
      in: path
      required: true
      description: The unique identifier of the document.
      schema:
        type: string
    TemplateId:
      name: template_id
      in: path
      required: true
      description: The unique identifier of the parsing template.
      schema:
        type: string
    WebhookId:
      name: webhook_id
      in: path
      required: true
      description: The unique identifier of the webhook.
      schema:
        type: string
  responses:
    Unauthorized:
      description: API key missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Mailbox:
      type: object
      properties:
        _id:
          type: string
        name:
          type: string
        email_prefix:
          type: string
          description: The inbound email address prefix for this mailbox.
        preset:
          type: string
          description: The parsing preset/engine bound to the mailbox.
        ml_model:
          type: string
          description: The AI/ML model used by AI or GPT parsers.
        has_raw_data:
          type: boolean
        parse_sig:
          type: boolean
          description: Whether email signatures are parsed.
        process_attachments:
          type: boolean
        collect_emails:
          type: boolean
        receive_email:
          type: boolean
        created_at:
          type: string
          format: date-time
    CreateMailboxRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        preset:
          type: string
        ml_model:
          type: string
        has_raw_data:
          type: boolean
        parse_sig:
          type: boolean
    UpdateMailboxRequest:
      type: object
      properties:
        name:
          type: string
        email_prefix:
          type: string
        process_attachments:
          type: boolean
        collect_emails:
          type: boolean
        alert_email_h:
          type: boolean
        receive_email:
          type: boolean
        preset:
          type: string
        ml_model:
          type: string
    TableField:
      type: object
      properties:
        _id:
          type: string
        name:
          type: string
        type:
          type: string
    ParseDocumentRequest:
      type: object
      properties:
        name:
          type: string
          description: Document identifier or subject line.
        html:
          type: string
          description: HTML markup to parse. Takes precedence over text when both are supplied.
        text:
          type: string
          description: Plain-text content to parse.
        from:
          type: string
          description: Sender address.
        to:
          type: string
          description: Recipient address.
        meta:
          type: object
          description: Custom metadata returned in the response as __meta__.
          additionalProperties: true
    UploadFileRequest:
      type: object
      required:
        - file
      properties:
        file:
          type: string
          format: binary
          description: The file to upload and parse.
        meta:
          type: string
          description: Custom payload as a JSON object or JSON-encoded string.
    Document:
      type: object
      properties:
        doc_id:
          type: string
        parsing_in_progress:
          type: boolean
        status:
          $ref: '#/components/schemas/DocumentStatus'
        name:
          type: string
        content_type:
          type: string
        created_at:
          type: string
          format: date-time
        processed_at:
          type: string
          format: date-time
        json:
          type: object
          description: The extracted structured data.
          additionalProperties: true
    DocumentStatus:
      type: string
      enum:
        - new
        - parsing
        - parsed
        - fail
        - skipped
        - quota
        - exception
    Template:
      type: object
      properties:
        _id:
          type: string
        name:
          type: string
        enabled:
          type: boolean
        mailbox_id:
          type: string
    Webhook:
      type: object
      properties:
        _id:
          type: string
        name:
          type: string
        url:
          type: string
          format: uri
        event:
          $ref: '#/components/schemas/WebhookEvent'
        enabled:
          type: boolean
        table_id:
          type: string
    CreateWebhookRequest:
      type: object
      required:
        - url
        - event
      properties:
        name:
          type: string
        url:
          type: string
          format: uri
        event:
          $ref: '#/components/schemas/WebhookEvent'
        enabled:
          type: boolean
        table_id:
          type: string
    UpdateWebhookRequest:
      type: object
      required:
        - _id
      properties:
        _id:
          type: string
        name:
          type: string
        url:
          type: string
          format: uri
        event:
          $ref: '#/components/schemas/WebhookEvent'
        enabled:
          type: boolean
        table_id:
          type: string
    WebhookEvent:
      type: string
      enum:
        - doc.parsed
        - doc.parsed.flat
        - doc.fail
        - doc.received
        - table.parsed
    IdsRequest:
      type: object
      required:
        - ids
      properties:
        ids:
          type: array
          items:
            type: string
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string