ARPI Inc. Authentication API

openapi: 3.2.0
info:
  title: ECG Buddy Authentication API
  description: 'Welcome to the **ECG Buddy API** 👋


    This API lets your system upload ECGs (images, or signal XML on the v2 engine) and get back AI-powered analysis results — all through a simple submit-and-poll flow. ---


    ## 🚀 Quick Start


    Get your first analysis result in 3 steps:


    **1. Get an access token**


    ```bash

    curl -X POST https://openapi.arpi.ai/api/v1/hospital/login \

    -H "Content-Type: application/json" \

    -d ''{"hospitalId": "your-client-id", "hospitalSecret": "your-client-secret"}''

    ```


    **2. Submit an image for analysis**


    ```bash

    curl -X POST https://openapi.arpi.ai/api/v1/diag \

    -H "Authorization: Bearer {accessToken}" \

    -F "file=@ecg.png"

    ```


    You''ll get a `jobId` back. Hold on to it. **3. Poll for the result**


    ```bash

    curl https://openapi.arpi.ai/api/v1/diag/{jobId}/result \

    -H "Authorization: Bearer {accessToken}"

    ```


    Poll every **2 seconds**. The response status tells you where you are:

    - `202` → still processing, keep polling

    - `200` → done! Result files are in the response

    - `500` → something went wrong (you can retry — see below)


    > ⏱️ **Tip:** Under heavy load a job may wait in the queue before processing begins; keep polling for up to ~15 minutes (450 attempts) before treating it as a timeout. ---


    ## 🔐 Authentication


    This API uses the **OAuth 2.0 Client Credentials Grant** flow. You authenticate with a **Client ID** and **Client Secret** to obtain a short-lived JWT access token, then send that token on every subsequent request. | Step | What you do |

    |------|-------------|

    | 1 | `POST /api/v1/hospital/login` with your **Client ID** and **Client Secret** |

    | 2 | Receive `accessToken` (JWT, expires in 5 minutes) |

    | 3 | Send `Authorization: Bearer {accessToken}` on every API request |

    | 4 | When the token expires, request a new one with the same credentials |


    > 📝 **Field naming note:** In the request body, your Client ID goes in the `hospitalId` field and your Client Secret goes in the `hospitalSecret` field. The field names are kept for backward compatibility — treat them as your standard OAuth 2.0 client credentials. > 🔑 **Need credentials?** Reach out to your Arpi contact if you already have one — otherwise email **support@arpi.ai** and we''ll get you set up. ---


    ## 📁 What you can submit


    ECG **images** work on any engine. **Signal XML** is supported on the **v2** engine — pass `?engine=v2` (see the submit endpoint). | Input | Formats | Engine |

    |-------|---------|--------|

    | ECG image | JPEG, PNG | v1, v2 |

    | Signal XML | GE MUSE, Philips, Fukuda (HL7 aECG), Nihon Kohden (MFER) | v2 only |


    - **Max size:** 20 MB. - **Signal XML needs `engine=v2`.** On the legacy v1 engine only images are analyzed; XML sent to v1 never completes and fails on timeout. - A successful signal-XML job returns the **same result types as an image job** (MAIN, GRAPHICAL, CARDIO, VHD, EU, comment). - An input the engine can''t interpret (unsupported/corrupt XML, unreadable image) is **not rejected at submit** — the job is accepted, then reported as **FAILED (`500 D999`)** when you poll `/result` (or via a FAILED callback). It stays retry-eligible for 24h. ---


    ## 🔄 Retry behavior


    If an analysis fails, you have **24 hours** to retry it for free using `POST /api/v1/diag/{jobId}/retry` — the same file is re-analyzed and your quota isn''t charged twice. After 24 hours, the deferred refund is processed automatically and you''ll need to submit a new analysis. ---


    ## 📊 Quota management


    Each client has daily and monthly analysis quotas based on your plan. - `GET /api/v1/diag/available` → Check what''s left right now

    - `GET /api/v1/diag/usage` → See historical usage (up to 90 days)


    If you hit the limit, submit calls will return `402 Payment Required` with code `S001`.'
  contact:
    name: Arpi
    email: support@arpi.ai
  version: v1
servers:
- url: https://openapi.arpi.ai
  description: prod
- url: https://openapi.dev.arpi.ai
  description: dev
tags:
- name: Authentication
  description: Token issuance endpoint using the OAuth 2.0 Client Credentials Grant. No prior authentication required — exchange your Client ID and Client Secret for a short-lived JWT access token.
paths:
  /api/v1/hospital/login:
    post:
      tags:
      - Authentication
      summary: Issue access token
      description: 'Issues a short-lived JWT access token using the **OAuth 2.0 Client Credentials Grant**.


        Send your Client ID and Client Secret in the request body to receive an access token. Use that token in the `Authorization: Bearer {accessToken}` header for all subsequent API requests.


        **Prerequisites**

        - You must have received your Client ID and Client Secret from Arpi. Contact your Arpi representative, or email `support@arpi.ai` if you don''t have one.


        **Flow**

        1. `POST /api/v1/hospital/login` with your credentials ← this endpoint

        - Invalid credentials → `401 H101`

        - Unknown Client ID → `404 H001`

        - Success → `accessToken` returned (valid for 5 minutes)

        2. Send `Authorization: Bearer {accessToken}` on subsequent requests

        3. When the token expires, call this endpoint again with the same credentials


        > 📝 **Note:** In the request body, your Client ID goes in `hospitalId` and your Client Secret goes in `hospitalSecret`. These field names are kept for backward compatibility. `appName` is optional — leave it out unless Arpi asked you to send a specific app identifier.'
      operationId: hospitalLogin
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HospitalTokenRequest'
        required: true
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HospitalTokenResponse'
        '400':
          description: 'Bad request. (C001: invalid parameter, C002: missing parameter, C003: malformed request, C004: validation failed)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 'Unauthorized. (H101: hospital authentication failed)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 'Not found. (H001: hospital not found)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 'Internal server error. (H102: failed to issue hospital token, H999: hospital operation failed)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/hospital/token:
    post:
      tags:
      - Authentication
      summary: Issue access token (legacy)
      description: '**Deprecated.** Identical behavior to `POST /api/v1/hospital/login`. New integrations should call `/login`; existing clients keep working. Scheduled for removal in a future release.'
      operationId: issueToken
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HospitalTokenRequest'
        required: true
      responses:
        '200':
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HospitalTokenResponse'
        '400':
          description: 'Bad request. (C001: invalid parameter, C002: missing parameter, C003: malformed request, C004: validation failed)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: 'Unauthorized. (H101: hospital authentication failed)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: 'Not found. (H001: hospital not found)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: 'Internal server error. (H102: failed to issue hospital token, H999: hospital operation failed)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      deprecated: true
components:
  schemas:
    ErrorResponse:
      type: object
      description: 에러 응답
      properties:
        timestamp:
          type: string
          format: date-time
          description: 에러 발생 시간
          example: '2026-01-26T17:30:00'
        status:
          type: integer
          format: int32
          description: HTTP 상태 코드
          example: 404
        error:
          type: string
          description: 에러 타입
          example: Not Found
        code:
          type: string
          description: '에러 코드 (도메인별 코드 체계 사용: D###, H### 등)'
          example: D001
        message:
          type: string
          description: 에러 메시지
          example: 리소스를 찾을 수 없습니다
        path:
          type: string
          description: 요청 경로
          example: /api/v1/diag/123
      required:
      - code
      - error
      - message
      - status
      - timestamp
    HospitalTokenRequest:
      type: object
      description: Access token request (OAuth 2.0 Client Credentials Grant)
      properties:
        hospitalId:
          type: string
          description: Your Client ID (issued by Arpi)
          example: hospital-abc
        hospitalSecret:
          type: string
          description: Your Client Secret (issued by Arpi)
          example: s3cr3t
        appName:
          type: string
          description: Optional calling-app identifier (a registered app policy). Omit or leave blank to use the default `openapi` policy. A supplied but unregistered value is rejected with 401 H101.
          example: ecg-buddy
      required:
      - hospitalId
      - hospitalSecret
    HospitalTokenResponse:
      type: object
      description: Access token response
      properties:
        access_token:
          type: string
          description: JWT access token
          example: eyJhbGci...
        expires_in:
          type: integer
          format: int32
          description: Token expiry in seconds
          example: 300
        token_type:
          type: string
          description: Token type
          example: Bearer
        hospital_id:
          type: string
          description: Internal client identifier (UUID)
          example: 550e8400-e29b-41d4-a716-446655440000
      required:
      - access_token
      - expires_in
      - hospital_id
      - token_type
  securitySchemes:
    bearerAuth:
      type: http
      description: JWT Bearer token obtained from POST /api/v1/hospital/login (OAuth 2.0 Client Credentials Grant). Valid for 5 minutes after issuance.
      scheme: bearer
      bearerFormat: JWT