openapi: 3.1.0
info:
  title: mATRIC API
  description: mATRIC API for managing users, agents, and third-party apps.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: /
security:
  - BearerAuth: []
paths:
  /token:
    post:
      tags:
        - token
      summary: Login
      operationId: login_token__post
      parameters:
        - name: login_type
          in: query
          description: 'Login type: user, agent or third_party_app'
          required: true
          style: form
          explode: true
          schema:
            title: Login Type
            description: 'Login type: user, agent or third_party_app'
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Body_login_token__post'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /users/public:
    post:
      tags:
        - users
      summary: Create First User
      operationId: create_first_user_users_public_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreate'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenData'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /users:
    get:
      tags:
        - users
      summary: List Users
      operationId: list_users_users__get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                title: Response List Users Users  Get
                items:
                  $ref: '#/components/schemas/TokenData'
    post:
      tags:
        - users
      summary: Create User
      operationId: create_user_users__post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreate'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenData'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - OAuth2PasswordBearer: []
  /users/{username}:
    get:
      tags:
        - users
      summary: Get User
      operationId: get_user_users__username__get
      parameters:
        - name: username
          in: path
          required: true
          style: simple
          explode: false
          schema:
            title: Username
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenData'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
        - users
      summary: Update User
      operationId: update_user_users__username__put
      parameters:
        - name: username
          in: path
          required: true
          style: simple
          explode: false
          schema:
            title: Username
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserUpdate'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenData'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - OAuth2PasswordBearer: []
    delete:
      tags:
        - users
      summary: Delete User
      operationId: delete_user_users__username__delete
      parameters:
        - name: username
          in: path
          required: true
          style: simple
          explode: false
          schema:
            title: Username
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                title: Response Delete User Users  Username  Delete
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - OAuth2PasswordBearer: []
  /users/me:
    get:
      tags:
        - users
      summary: Read Users Me
      operationId: read_users_me_users_me_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenData'
      security:
        - OAuth2PasswordBearer: []
  /agents/public:
    post:
      tags:
        - agents
      summary: Create First Agent
      operationId: create_first_agent_agents_public_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentCreate'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /agents:
    post:
      tags:
        - agents
      summary: Create Agent
      operationId: create_agent_agents__post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentCreate'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - OAuth2PasswordBearer: []
  /agents/{ap_id}:
    get:
      tags:
        - agents
      summary: Get Agent
      operationId: get_agent_agents__ap_id__get
      parameters:
        - name: ap_id
          in: path
          required: true
          style: simple
          explode: false
          schema:
            title: Ap Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - OAuth2PasswordBearer: []
    put:
      tags:
        - agents
      summary: Update Agent
      operationId: update_agent_agents__ap_id__put
      parameters:
        - name: ap_id
          in: path
          required: true
          style: simple
          explode: false
          schema:
            title: Ap Id
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentUpdate'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - OAuth2PasswordBearer: []
    delete:
      tags:
        - agents
      summary: Delete Agent
      operationId: delete_agent_agents__ap_id__delete
      parameters:
        - name: ap_id
          in: path
          required: true
          style: simple
          explode: false
          schema:
            title: Ap Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                title: Response Delete Agent Agents  Ap Id  Delete
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - OAuth2PasswordBearer: []
  /third_party_apps:
    post:
      tags:
        - third_party_apps
      summary: Create Third Party App
      operationId: create_third_party_app_third_party_apps__post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ThirdPartyAppCreate'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThirdPartyApp'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - OAuth2PasswordBearer: []
  /third_party_apps/{app_name}:
    get:
      tags:
        - third_party_apps
      summary: Get Third Party App
      operationId: get_third_party_app_third_party_apps__app_name__get
      parameters:
        - name: app_name
          in: path
          required: true
          style: simple
          explode: false
          schema:
            title: App Name
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThirdPartyApp'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - OAuth2PasswordBearer: []
    put:
      tags:
        - third_party_apps
      summary: Update Third Party App
      operationId: update_third_party_app_third_party_apps__app_name__put
      parameters:
        - name: app_name
          in: path
          required: true
          style: simple
          explode: false
          schema:
            title: App Name
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ThirdPartyAppUpdate'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThirdPartyApp'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - OAuth2PasswordBearer: []
    delete:
      tags:
        - third_party_apps
      summary: Delete Third Party App
      operationId: delete_third_party_app_third_party_apps__app_name__delete
      parameters:
        - name: app_name
          in: path
          required: true
          style: simple
          explode: false
          schema:
            title: App Name
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                title: >-
                  Response Delete Third Party App Third Party Apps  App Name 
                  Delete
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - OAuth2PasswordBearer: []
  /agent_update/update:
    post:
      tags:
        - agent_update
      summary: Update Agent
      operationId: update_agent_agent_update_update_post
      requestBody:
        content:
          application/json:
            schema:
              title: Data
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                title: Response Update Agent Agent Update Update Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - OAuth2PasswordBearer: []
  /agent_details/request_all_agents_details:
    post:
      tags:
        - agent_details
      summary: Request All Agents Details
      description: |-
        Endpoint to request details for all agents.
        Only authenticated users and third-party apps can access this.
      operationId: request_all_agents_details_agent_details_request_all_agents_details_post
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
      security:
        - OAuth2PasswordBearer: []
  /agent_data/request_agent_data:
    post:
      tags:
        - agent_data
      summary: Request Agent Data
      description: |-
        Endpoint to request agent data for a specific period.
        Both authenticated agents and users can request agent data.
      operationId: request_agent_data_agent_data_request_agent_data_post
      parameters:
        - name: agent_id
          in: query
          required: true
          style: form
          explode: true
          schema:
            title: Agent Id
        - name: start_time
          in: query
          required: true
          style: form
          explode: true
          schema:
            title: Start Time
            format: date-time
        - name: end_time
          in: query
          required: true
          style: form
          explode: true
          schema:
            title: End Time
            format: date-time
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - OAuth2PasswordBearer: []
  /send_command:
    post:
      tags:
        - send_command
      summary: Send Command To Agent
      description: |-
        Endpoint to send a command to a specific agent.
        Only authenticated third-party apps can send commands.
      operationId: send_command_to_agent_send_command_post
      parameters:
        - name: agent_id
          in: query
          required: true
          style: form
          explode: true
          schema:
            title: Agent Id
        - name: command
          in: query
          required: true
          style: form
          explode: true
          schema:
            title: Command
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - OAuth2PasswordBearer: []
  /callback/agent_data:
    post:
      tags:
        - agent_data_callback
      summary: Agent Data Callback
      description: >-
        Callback endpoint to receive agent data from the subscriber.

        The data will be sent to the WebSocket client identified by the
        job_number.
      operationId: agent_data_callback_callback_agent_data_post
      parameters:
        - name: job_number
          in: query
          required: true
          style: form
          explode: true
          schema:
            title: Job Number
      requestBody:
        content:
          application/json:
            schema:
              title: Data
              items: {}
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /callback/agent_details:
    post:
      tags:
        - agent_details_callback
      summary: Agent Details Callback
      description: >-
        Callback endpoint to receive agent details from the subscriber.

        The agent details will be sent to the WebSocket client identified by the
        job_number.
      operationId: agent_details_callback_callback_agent_details_post
      parameters:
        - name: job_number
          in: query
          required: true
          style: form
          explode: true
          schema:
            title: Job Number
      requestBody:
        content:
          application/json:
            schema:
              title: Agent Details
              items: {}
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    Agent:
      title: Agent
      required:
        - ap_id
        - configuration
        - id
      properties:
        id:
          title: Id
          format: uuid
        ap_id:
          title: Ap Id
        configuration:
          title: Configuration
    AgentCreate:
      title: AgentCreate
      required:
        - ap_id
        - configuration
        - password
      properties:
        ap_id:
          title: Ap Id
        password:
          title: Password
        configuration:
          title: Configuration
    AgentUpdate:
      title: AgentUpdate
      properties:
        password:
          title: Password
          anyOf:
            - {}
            - {}
        configuration:
          title: Configuration
          anyOf:
            - {}
            - {}
    Body_login_token__post:
      title: Body_login_token__post
      required:
        - password
        - username
      properties:
        grant_type:
          title: Grant Type
          anyOf:
            - pattern: password
            - {}
        username:
          title: Username
        password:
          title: Password
        scope:
          title: Scope
          default: ''
        client_id:
          title: Client Id
          anyOf:
            - {}
            - {}
        client_secret:
          title: Client Secret
          anyOf:
            - {}
            - {}
    HTTPValidationError:
      title: HTTPValidationError
      properties:
        detail:
          title: Detail
          items:
            $ref: '#/components/schemas/ValidationError'
    ThirdPartyApp:
      title: ThirdPartyApp
      required:
        - api_key
        - app_name
        - id
        - permissions
      properties:
        id:
          title: Id
          format: uuid
        app_name:
          title: App Name
        api_key:
          title: Api Key
        permissions:
          title: Permissions
    ThirdPartyAppCreate:
      title: ThirdPartyAppCreate
      required:
        - api_key
        - app_name
        - permissions
      properties:
        app_name:
          title: App Name
        api_key:
          title: Api Key
        permissions:
          title: Permissions
    ThirdPartyAppUpdate:
      title: ThirdPartyAppUpdate
      properties:
        api_key:
          title: Api Key
          anyOf:
            - {}
            - {}
        permissions:
          title: Permissions
          anyOf:
            - {}
            - {}
    Token:
      title: Token
      required:
        - access_token
        - expires_in
        - token_type
      properties:
        access_token:
          title: Access Token
        token_type:
          title: Token Type
        expires_in:
          title: Expires In
    TokenData:
      title: TokenData
      required:
        - roles
      properties:
        username:
          title: Username
          anyOf:
            - {}
            - {}
        roles:
          title: Roles
        scopes:
          title: Scopes
          items: {}
          default: []
    UserCreate:
      title: UserCreate
      required:
        - password
        - roles
        - username
      properties:
        username:
          title: Username
          format: email
        password:
          title: Password
        roles:
          title: Roles
          items: {}
    UserUpdate:
      title: UserUpdate
      properties:
        password:
          title: Password
          anyOf:
            - {}
            - {}
        roles:
          title: Roles
          anyOf:
            - items: {}
            - {}
    ValidationError:
      title: ValidationError
      required:
        - loc
        - msg
        - type
      properties:
        loc:
          title: Location
          items:
            anyOf:
              - {}
              - {}
        msg:
          title: Message
        type:
          title: Error Type
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
