openapi: 3.1.0
info:
  title: Shuffle Administration Files API
  description: Shuffle is an open source security automation platform (SOAR) built for and by security professionals. The Shuffle REST API provides programmatic access to all platform capabilities including workflow management, app integration, execution control, user management, organization administration, file storage, datastore operations, and webhook triggers. Everything available in the Shuffle frontend is accessible via the API.
  version: v1
  contact:
    name: Shuffle Support
    url: https://shuffler.io/docs
    email: frikky@shuffler.io
  license:
    name: Apache 2.0
    url: https://github.com/Shuffle/Shuffle/blob/main/LICENSE
servers:
- url: https://shuffler.io/api/v1
  description: Shuffle Cloud
- url: https://{domain}/api/v1
  description: Shuffle On-Premises
  variables:
    domain:
      description: Your Shuffle instance domain
      default: localhost
security:
- BearerAuth: []
tags:
- name: Files
paths:
  /files/create:
    post:
      operationId: createFile
      summary: Create File
      description: Creates a file record in the Shuffle file store.
      tags:
      - Files
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - filename
              - org_id
              properties:
                filename:
                  type: string
                  description: Name of the file
                org_id:
                  type: string
                  description: Organization ID
                workflow_id:
                  type: string
                  description: Associated workflow ID
                namespace:
                  type: string
                  description: File namespace for grouping
      responses:
        '200':
          description: File record created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File'
  /files:
    get:
      operationId: listFiles
      summary: List Files
      description: Returns all files accessible to the organization.
      tags:
      - Files
      responses:
        '200':
          description: List of files
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/File'
  /files/{id}/upload:
    post:
      operationId: uploadFile
      summary: Upload File Content
      description: Uploads content to an existing file record.
      tags:
      - Files
      parameters:
      - name: id
        in: path
        required: true
        description: File ID
        schema:
          type: string
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: File content uploaded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
  /files/{id}/content:
    get:
      operationId: getFileContent
      summary: Get File Content
      description: Downloads the content of a file.
      tags:
      - Files
      parameters:
      - name: id
        in: path
        required: true
        description: File ID
        schema:
          type: string
      responses:
        '200':
          description: File content
  /files/{id}:
    post:
      operationId: getFileMetadata
      summary: Get File Metadata
      description: Retrieves metadata for a specific file.
      tags:
      - Files
      parameters:
      - name: id
        in: path
        required: true
        description: File ID
        schema:
          type: string
      responses:
        '200':
          description: File metadata
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/File'
    delete:
      operationId: deleteFile
      summary: Delete File
      description: Deletes a file from the file store.
      tags:
      - Files
      parameters:
      - name: id
        in: path
        required: true
        description: File ID
        schema:
          type: string
      - name: remove_metadata
        in: query
        description: Whether to also remove file metadata
        schema:
          type: boolean
      responses:
        '200':
          description: File deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponse'
components:
  schemas:
    File:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        org_id:
          type: string
        workflow_id:
          type: string
        namespace:
          type: string
        created:
          type: integer
        status:
          type: string
        file_size:
          type: integer
    ApiResponse:
      type: object
      properties:
        success:
          type: boolean
          description: Whether the operation was successful
        reason:
          type: string
          description: Optional error message if success is false
        id:
          type: string
          description: Optional ID of created/affected resource
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'API key obtained from Shuffle profile settings. Include as: Authorization: Bearer <APIKEY>'