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

# Receive detector scan

> Send one AEI detector pass, or one OS traffic file, to ARMS. This is the same CSV a railroad can upload over SFTP, and ARMS reads it the same way: the scan appears on the AEI scans page, is matched to the cars in inventory and to the train, and can start AEI automation.

Usage notes:
- Send the file's text, unchanged, as `message`. A detector CSV starts with a summary line (such as `Total cars: 20`), which is skipped; the second line is the header row, which must include `Car Number`, `MilePost`, `Scanning Datetime` and `From`. Every row must have the same `MilePost`, and the cars are kept in the order sent.
- An OS traffic CSV has the header `SequenceNo,MilePost,Direction,Timestamp` on its first line. Its latest row sets where the train is; it carries no cars.
- Times are the railroad's local time, as `YYYY-MM-DD HH:MM:SS`.
- Send `trainId` to say which train the scan belongs to; alternatively, a `fileName` of the form `TRAINID_YYYYMMDD_HHMMSS.csv`, as on SFTP, sets it. An OS traffic file is matched only to the train with that ID, so always send one with OS traffic files. A detector pass is matched to trains by its cars, and its train ID is stored with the scan. `fileName` is a bare file name, without folders. `fileName` and `trainId` may use only letters, digits, `.`, `_` and `-`, and must start with a letter or digit.
- A car number other than letters followed by digits is stored as a bad read, and the rest of the scan is kept.
- A scan older than the railroad's AEI scan-age limit (2 hours unless the railroad has changed it) is stored but not matched to inventory, and starts no automation; the request still returns 200. A scan more than 5 minutes in the future is refused with 400.
- At most 1,000,000 characters and 2,000 rows per request.
- Resending exactly the same body (`message`, `trainId` and `fileName`), such as a retry after a timeout, returns 409 with `errorArgs.aeiId` naming the scan the first request created. Retry with the same body rather than rebuilding the CSV. A resend that adds or corrects `trainId` or `fileName` creates a new scan.
- Files sent over SFTP are not checked against files sent here. Send each file over one channel only, or it is received twice.
- A CSV without a `MilePost` column is refused with 400.
- A missing permission returns 401.



## OpenAPI

````yaml /user-docs/api-reference/external-openapi.json post /mhs/aei/detector/messages:receive-external
openapi: 3.1.0
info:
  title: ARMS External API
  version: 1.0.0
  description: >-
    OpenAPI specification generated from external API schemas. Endpoints require
    query parameter carrierId and headers x-arms-api-key and x-arms-assume-user.
  license:
    name: Proprietary
    url: https://cedarai.com
servers:
  - url: https://api-lg.arms.cedarai.com
    description: Production (US)
  - url: https://api-lg.arms.cedarai.se
    description: Production (EU)
security:
  - ApiKeyAuth: []
    AssumeUser: []
paths:
  /mhs/aei/detector/messages:receive-external:
    post:
      summary: Receive detector scan
      description: >-
        Send one AEI detector pass, or one OS traffic file, to ARMS. This is the
        same CSV a railroad can upload over SFTP, and ARMS reads it the same
        way: the scan appears on the AEI scans page, is matched to the cars in
        inventory and to the train, and can start AEI automation.


        Usage notes:

        - Send the file's text, unchanged, as `message`. A detector CSV starts
        with a summary line (such as `Total cars: 20`), which is skipped; the
        second line is the header row, which must include `Car Number`,
        `MilePost`, `Scanning Datetime` and `From`. Every row must have the same
        `MilePost`, and the cars are kept in the order sent.

        - An OS traffic CSV has the header
        `SequenceNo,MilePost,Direction,Timestamp` on its first line. Its latest
        row sets where the train is; it carries no cars.

        - Times are the railroad's local time, as `YYYY-MM-DD HH:MM:SS`.

        - Send `trainId` to say which train the scan belongs to; alternatively,
        a `fileName` of the form `TRAINID_YYYYMMDD_HHMMSS.csv`, as on SFTP, sets
        it. An OS traffic file is matched only to the train with that ID, so
        always send one with OS traffic files. A detector pass is matched to
        trains by its cars, and its train ID is stored with the scan. `fileName`
        is a bare file name, without folders. `fileName` and `trainId` may use
        only letters, digits, `.`, `_` and `-`, and must start with a letter or
        digit.

        - A car number other than letters followed by digits is stored as a bad
        read, and the rest of the scan is kept.

        - A scan older than the railroad's AEI scan-age limit (2 hours unless
        the railroad has changed it) is stored but not matched to inventory, and
        starts no automation; the request still returns 200. A scan more than 5
        minutes in the future is refused with 400.

        - At most 1,000,000 characters and 2,000 rows per request.

        - Resending exactly the same body (`message`, `trainId` and `fileName`),
        such as a retry after a timeout, returns 409 with `errorArgs.aeiId`
        naming the scan the first request created. Retry with the same body
        rather than rebuilding the CSV. A resend that adds or corrects `trainId`
        or `fileName` creates a new scan.

        - Files sent over SFTP are not checked against files sent here. Send
        each file over one channel only, or it is received twice.

        - A CSV without a `MilePost` column is refused with 400.

        - A missing permission returns 401.
      operationId: receiveDetectorScan
      parameters:
        - $ref: '#/components/parameters/CarrierId'
        - $ref: '#/components/parameters/ViewAsUserGroup'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReceiveDetectorScanInput'
            examples:
              detector:
                summary: A detector pass of a train
                value:
                  carrierId: 1234
                  message: >
                    Total cars: 2

                    Car Number,Track ID,MilePost,Position,Spot
                    Name,Status,Scanning Method,Orientation,Type,Scanning
                    Datetime,From,To

                    AMMC000097,Main,243,1,,,Automatic,NotAvailable,Locomotive,2026-11-20
                    08:05:00,North,South

                    CFC
                    000672,Main,243,2,,,Automatic,NotAvailable,Railcar,2026-11-20
                    08:05:00,North,South
                  trainId: M151
              osTraffic:
                summary: An OS traffic file
                value:
                  carrierId: 1234
                  message: |
                    SequenceNo,MilePost,Direction,Timestamp
                    1,0,North,2026-11-20 07:40:12
                    39,234,North,2026-11-20 08:05:00
                  fileName: C910V_20261120_080500.csv
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReceiveDetectorScanOutput'
        '400':
          description: >-
            Bad Request (the CSV could not be read, has too many rows, or is
            dated in the future; nothing was stored)
        '401':
          description: Unauthorized (bad key, carrier not permitted, or missing permission)
        '409':
          description: >-
            Conflict (this railroad already received exactly this body;
            `errorArgs.aeiId` names the scan it created)
        '500':
          description: Internal Server Error (nothing was stored; safe to retry)
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    CarrierId:
      name: carrierId
      in: query
      required: true
      schema:
        type: integer
      description: Carrier identifier; required for all endpoints
    ViewAsUserGroup:
      name: viewAsUserGroup
      in: query
      required: false
      schema:
        type: string
      description: Optional user group context
  schemas:
    ReceiveDetectorScanInput:
      type: object
      required:
        - carrierId
        - message
      properties:
        carrierId:
          type: integer
          format: int64
          description: >-
            The railroad's carrier ID. Must match the `carrierId` query
            parameter.
        message:
          type: string
          maxLength: 1000000
          description: The detector or OS traffic CSV, as text.
        fileName:
          type: string
          maxLength: 128
          pattern: ^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$
          description: >-
            Optional bare file name (no folders), stored with the scan.
            `TRAINID_YYYYMMDD_HHMMSS.csv` also sets the train ID, unless
            `trainId` is sent.
        trainId:
          type: string
          maxLength: 128
          pattern: ^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$
          description: >-
            Optional ID of the train the scan belongs to. OS traffic files are
            matched only to this train; detector passes are matched by their
            cars.
    ReceiveDetectorScanOutput:
      type: object
      properties:
        aeiConsist:
          type: object
          description: The scan ARMS created. Further fields may be added.
          properties:
            aeiId:
              type: string
              description: ID of the scan, as shown on the AEI scans page.
            siteId:
              type: string
              description: >-
                `DETECTOR` for a detector pass, `OS_TRAFFIC` for an OS traffic
                file.
            direction:
              type: string
              description: 'Direction the train was headed: `N`, `S`, `E` or `W`.'
            scanTimestamp:
              type: string
              format: date-time
            milepost:
              type: string
            sourceTrainId:
              type: string
              description: The train ID, from `trainId` or `fileName`.
            filepath:
              type: string
              description: The `fileName` sent, if any.
            equipmentStubs:
              type: array
              items:
                $ref: '#/components/schemas/ReceiveDetectorScanEquipment'
              description: The cars read, in the order sent.
    Error:
      type: object
      properties:
        message:
          type: string
    ReceiveDetectorScanEquipment:
      type: object
      properties:
        equipmentInitial:
          type: string
          description: Reporting mark, or `NONE` for a bad read.
        equipmentNumber:
          type: integer
          description: Car number.
        tagStatus:
          type: string
          description: How the tag was read, for example `NOREAD` for a bad read.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-arms-api-key
      description: Your ARMS API key
    AssumeUser:
      type: apiKey
      in: header
      name: x-arms-assume-user
      description: Email of a user assigned to the appropriate user group

````

## Related topics

- [API Introduction](https://docs.cedarai.com/user-docs/api-reference/introduction.md)
- [Interchanges](https://docs.cedarai.com/user-docs/mobile/interchanges.md)
- [Ingate trucks one after another](https://docs.cedarai.com/user-docs/arms/ops/ingate-trucks.md)
- [Train Arrival Webhook](https://docs.cedarai.com/user-docs/arms/webhooks/train-arrival.md)
- [Train Departure Webhook](https://docs.cedarai.com/user-docs/arms/webhooks/train-departure.md)
