HHS (US Department of Health and Human Services) File v1 API

openapi: 3.1.0
info:
  description: '

    Back end API for simpler.grants.gov.


    This API is in active development as we build out new functionalities for Simpler.Grants.gov. It is currently stable for everyday use, and will be versioned with advance notice for any breaking changes.


    Learn more in our [API documentation](https://wiki.simpler.grants.gov/product/api).

    See [Release Phases](https://github.com/github/roadmap?tab=readme-ov-file#release-phases) for further details.

    '
  contact:
    name: Simpler Grants.gov
    url: https://simpler.grants.gov/
    email: simpler@grants.gov
  title: Simpler Grants File v1 API
  version: v0
servers: .
tags:
- name: File v1
paths:
  /v1/files/{pending_file_id}/results:
    get:
      parameters:
      - in: path
        name: pending_file_id
        schema:
          type: string
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FileScanResultsResponseSchema'
          description: Successful response
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Authentication error
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Not found
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponseSchema'
          description: Forbidden
      tags:
      - File v1
      summary: Stream file scan results
      description: Stream the scan status of a pending file as newline-delimited JSON. Each chunk matches the documented response schema. The endpoint polls DynamoDB on a configurable interval and ends the stream when the scan reaches a terminal status (complete/infected) or the configured max duration elapses.
      security:
      - ApiJwtAuth: &id001 []
      - ApiUserKeyAuth: *id001
components:
  schemas:
    FileScanResultsDataSchema:
      type: object
      properties:
        status:
          description: The current scan status of the file
          example:
          - pending
          enum:
          - pending
          - in_progress
          - complete
          - infected
          type:
          - string
      required:
      - status
    FileScanResultsResponseSchema:
      type: object
      properties:
        data:
          type:
          - object
          $ref: '#/components/schemas/FileScanResultsDataSchema'
      required:
      - data
    ValidationIssueSchema:
      type: object
      properties:
        type:
          type: string
          description: The type of error
          example: invalid
        message:
          type: string
          description: The message to return
          example: Not a valid string.
        field:
          type: string
          description: The field that failed
          example: summary.summary_description
        value:
          type: string
          description: The value that failed
          example: invalid string
    ErrorResponseSchema:
      type: object
      properties:
        data:
          description: Additional data that might be useful in resolving an error (see specific endpoints for details, this is used infrequently)
          example: {}
        message:
          type: string
          description: General description of the error
          example: Error
        status_code:
          type: integer
          description: The HTTP status code of the error
        errors:
          type: array
          example: []
          items:
            type:
            - object
            $ref: '#/components/schemas/ValidationIssueSchema'
        internal_request_id:
          type: string
          description: An internal tracking ID
          example: 550e8400-e29b-41d4-a716-446655440000
  securitySchemes:
    ApiJwtAuth:
      type: apiKey
      in: header
      name: X-SGG-Token
    InternalApiJwtAuth:
      type: apiKey
      in: header
      name: X-SGG-Internal-Token
    ApiUserKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key