openapi: 3.0.4
info:
  title: Calyptia Cloud agent agent_error API
  version: '1.0'
  description: HTTP API service of Calyptia Cloud
  contact:
    name: Calyptia
    email: hello@calyptia.com
    url: https://cloud.calyptia.com
  termsOfService: https://calyptia.com/terms/
servers:
- url: https://cloud-api.calyptia.com
  description: prod
- url: https://cloud-api-dev.calyptia.com
  description: dev
- url: https://cloud-api-staging.calyptia.com
  description: staging
- url: http://localhost:{port}
  description: local
  variables:
    port:
      default: '5000'
tags:
- name: agent_error
paths:
  /v1/agents/{agentID}/errors:
    parameters:
    - name: agentID
      in: path
      required: true
      schema:
        type: string
        format: uuid
    post:
      operationId: createAgentError
      summary: Create agent error
      description: 'Create a new agent error.

        This endpoint should be called directly by agents themselves.

        Notice that if there is an error that matches exactly

        and has not been dismissed yet

        since the last time the config was updated,

        then the error will be simply ignored and not persisted.'
      security:
      - project: []
      tags:
      - agent_error
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentError'
      responses:
        201:
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatedAgentError'
    get:
      operationId: agentErrors
      summary: Agent errors
      description: 'List all agent errors in descending order with backward pagination.

        You can optionally filter dismissed or not dismissed errors.'
      security:
      - user: []
      - project: []
      tags:
      - agent_error
      parameters:
      - name: dismissed
        in: query
        required: false
        schema:
          type: boolean
        description: Filter agent errors that either were dismissed or were not.
      - name: last
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
        description: Last agent errors.
      - name: before
        in: query
        required: false
        schema:
          type: string
        description: Agents errors before the given cursor.
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AgentError'
          headers:
            Link:
              schema:
                type: string
                example: </v1/agents/foo/errors?before=bar>; rel="next"
              description: RFC5988 with `rel="next"`.
          links:
            NextFleetsPage:
              operationId: agentErrors
              parameters:
                before: $response.header.Link#rel=next
  /v1/fleets/{fleetID}/agent_errors:
    parameters:
    - name: fleetID
      in: path
      required: true
      schema:
        type: string
        format: uuid
    get:
      operationId: fleetAgentErrors
      summary: Fleet agent errors
      description: 'List all agent errors from the given fleet

        in descending order with backward pagination.

        You can optionally filter dismissed or not dismissed errors.'
      security:
      - user: []
      - project: []
      tags:
      - agent_error
      parameters:
      - name: dismissed
        in: query
        required: false
        schema:
          type: boolean
        description: Filter agent errors that either were dismissed or were not.
      - name: last
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
        description: Last agent errors.
      - name: before
        in: query
        required: false
        schema:
          type: string
        description: Agents errors before the given cursor.
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AgentError'
          headers:
            Link:
              schema:
                type: string
                example: </v1/fleets/foo/agent_errors?before=bar>; rel="next"
              description: RFC5988 with `rel="next"`.
          links:
            NextFleetsPage:
              operationId: fleetAgentErrors
              parameters:
                before: $response.header.Link#rel=next
  /v1/agent_errors/{agentErrorID}/dismiss:
    post:
      operationId: dismissAgentError
      summary: Dismiss agent error
      description: Dismiss the given agent error. You must pass the reason for dismissal.
      security:
      - user: []
      - project: []
      tags:
      - agent_error
      parameters:
      - name: agentErrorID
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DismissAgentError'
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DismissedAgentError'
components:
  schemas:
    AgentError:
      type: object
      description: 'An Agent Error represent an error that occurred on an agent.

        It can be an invalid configuration, or a malfunctioning plugin.

        These come directly from agents.

        Any agent that has errors since the last time it was updated

        will be marked as "errored".

        Errors can be dismissed by the user.'
      properties:
        id:
          type: string
          format: uuid
        agentID:
          type: string
          format: uuid
        error:
          type: string
          example: '[config] section ''foo'' tried to instance a plugin name that don''t exists'
        dismissedAt:
          type: string
          format: date-time
          nullable: true
          default: null
        dismissReason:
          type: string
          nullable: true
          default: null
        createdAt:
          type: string
          format: date-time
      required:
      - id
      - agentID
      - error
      - dismissedAt
      - dismissReason
      - createdAt
    CreateAgentError:
      type: object
      description: Request body required to create a new Agent Error.
      properties:
        error:
          type: string
          minLength: 1
          maxLength: 1024
          example: '[config] section ''foo'' tried to instance a plugin name that don''t exists'
      required:
      - error
    CreatedAgentError:
      type: object
      description: Response body after creating a new Agent Error.
      properties:
        id:
          type: string
          format: uuid
        createdAt:
          type: string
          format: date-time
      required:
      - id
      - createdAt
    DismissedAgentError:
      type: object
      description: Response body after dismissing an Agent Error.
      properties:
        dismissedAt:
          type: string
          format: date-time
      required:
      - dismissedAt
    DismissAgentError:
      type: object
      description: Request body required to dismiss an existing agent error.
      properties:
        reason:
          type: string
          minLength: 1
          maxLength: 100
          example: It was just a test, this config is not used in production.
      required:
      - reason
  securitySchemes:
    user:
      type: http
      scheme: bearer
    project:
      name: X-Project-Token
      type: apiKey
      in: header
    auth0:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://sso.calyptia.com/oauth/token
          scopes: {}
        authorizationCode:
          authorizationUrl: https://sso.calyptia.com/authorize
          tokenUrl: https://sso.calyptia.com/oauth/token
          scopes: {}