Mavrck External Clients API

openapi: 3.2.0
info:
  version: 1.0.0
  description: Identify your most influential customers and activate them to drive more conversions on social.
  title: MAVRCK.IO External Clients API
servers:
- url: http://app.splashscore.com/v1
- url: https://app.splashscore.com/v1
security:
- apiKey: []
tags:
- name: ExternalClients
paths:
  /v1/admin/external-clients:
    post:
      operationId: createExternalClient
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateExternalClientResponse'
        '400':
          description: Missing Parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateErrorJSON'
        '403':
          description: Access Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
      description: Create a new external client
      tags:
      - ExternalClients
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateExternalClientBody'
        description: The client details (name required, clientId and clientSecret optional for migration)
        required: true
    get:
      operationId: getAllExternalClients
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAllClientsResponse'
        '400':
          description: Missing Parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateErrorJSON'
        '403':
          description: Access Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
      description: 'Get all clients with their instances, or filter by clientId.

        Includes deleted clients and separates active/inactive instances.'
      tags:
      - ExternalClients
      parameters:
      - description: Optional client ID to filter results
        in: query
        name: clientId
        required: false
        schema:
          type: string
      - description: 'Page number (default: 1)'
        in: query
        name: page
        required: false
        schema:
          type: number
          format: double
          default: 1
      - description: 'Number of results per page (default: 20, max: 100)'
        in: query
        name: pageSize
        required: false
        schema:
          type: number
          format: double
          default: 20
  /v1/admin/external-clients/{clientId}/secrets:
    post:
      operationId: regenerateExternalClientSecret
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegenerateSecretResponse'
        '400':
          description: Missing Parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateErrorJSON'
        '403':
          description: Access Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
      description: Regenerate the client secret
      tags:
      - ExternalClients
      parameters:
      - description: The unique identifier for the client
        in: path
        name: clientId
        required: true
        schema:
          type: string
  /v1/admin/external-clients/{clientId}:
    delete:
      operationId: deleteExternalClient
      responses:
        '204':
          description: No Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmptySuccessResponse'
        '400':
          description: Missing Parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateErrorJSON'
        '403':
          description: Access Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
      description: Soft delete a client and all associated instances
      tags:
      - ExternalClients
      parameters:
      - description: The unique identifier for the client
        in: path
        name: clientId
        required: true
        schema:
          type: string
  /v1/admin/external-clients/{clientId}/instances:
    post:
      operationId: associateExternalClientInstances
      responses:
        '204':
          description: No Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmptySuccessResponse'
        '400':
          description: Missing Parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateErrorJSON'
        '403':
          description: Access Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
      description: Associate instances to a client
      tags:
      - ExternalClients
      parameters:
      - description: The unique identifier for the client
        in: path
        name: clientId
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssociateInstancesBody'
        description: The instance IDs to associate
        required: true
  /v1/admin/external-clients/{clientId}/instances/{instanceId}:
    delete:
      operationId: deleteExternalClientInstance
      responses:
        '204':
          description: No Content
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmptySuccessResponse'
        '400':
          description: Missing Parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateErrorJSON'
        '403':
          description: Access Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
        '404':
          description: Resource Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
      description: Soft delete a client instance association
      tags:
      - ExternalClients
      parameters:
      - description: The unique identifier for the client
        in: path
        name: clientId
        required: true
        schema:
          type: string
      - description: The instance ID to remove
        in: path
        name: instanceId
        required: true
        schema:
          type: string
components:
  schemas:
    EmptySuccessResponse:
      description: Empty success response
      properties: {}
      type: object
      additionalProperties: false
    AssociateInstancesBody:
      description: Request body for associating instances
      properties:
        instanceIds:
          items:
            type: string
          type: array
      required:
      - instanceIds
      type: object
      additionalProperties: false
    GetAllClientsResponse:
      description: Paginated response for getting all clients with instances
      properties:
        clients:
          items:
            $ref: '#/components/schemas/ClientWithInstances'
          type: array
        pagination:
          properties:
            totalPages:
              type: number
              format: double
            pageSize:
              type: number
              format: double
            page:
              type: number
              format: double
            total:
              type: number
              format: double
          required:
          - totalPages
          - pageSize
          - page
          - total
          type: object
      required:
      - clients
      - pagination
      type: object
      additionalProperties: false
    CreateExternalClientBody:
      description: Request body for creating an external client
      properties:
        name:
          type: string
        clientId:
          type: string
        clientSecret:
          type: string
      required:
      - name
      type: object
      additionalProperties: false
    CreateExternalClientResponse:
      properties:
        clientId:
          type: string
        clientSecret:
          type: string
        name:
          type: string
        createdAt:
          type: string
          format: date-time
      required:
      - clientId
      - clientSecret
      - name
      - createdAt
      type: object
      additionalProperties: false
    ForbiddenError:
      properties:
        message:
          type: string
          enum:
          - Access Forbidden
        details:
          properties: {}
          additionalProperties:
            additionalProperties: true
          type: object
      required:
      - message
      - details
      type: object
      additionalProperties: false
    RegenerateSecretResponse:
      properties:
        clientId:
          type: string
        clientSecret:
          type: string
        regeneratedAt:
          type: string
          format: date-time
      required:
      - clientId
      - clientSecret
      - regeneratedAt
      type: object
      additionalProperties: false
    NotFoundError:
      properties:
        message:
          type: string
          enum:
          - Resource Not Found
        details:
          properties: {}
          additionalProperties:
            additionalProperties: true
          type: object
      required:
      - message
      - details
      type: object
      additionalProperties: false
    ServerError:
      properties:
        message:
          type: string
          enum:
          - Server Error
        details:
          properties: {}
          additionalProperties:
            additionalProperties: true
          type: object
      required:
      - message
      - details
      type: object
      additionalProperties: false
    ClientWithInstances:
      description: Client with active and inactive instances
      properties:
        clientId:
          type: string
        name:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
        deletedAt:
          type:
          - string
          - 'null'
          format: date-time
        connectedInstances:
          items:
            type: string
          type: array
        disconnectedInstances:
          items:
            type: string
          type: array
      required:
      - clientId
      - name
      - createdAt
      - updatedAt
      - deletedAt
      - connectedInstances
      - disconnectedInstances
      type: object
      additionalProperties: false
    ValidateErrorJSON:
      properties:
        message:
          type: string
          enum:
          - Validation failed
        details:
          properties: {}
          additionalProperties:
            additionalProperties: true
          type: object
      required:
      - message
      - details
      type: object
      additionalProperties: false
  securitySchemes:
    apiKey:
      type: apiKey
      name: api-key
      in: header